git.gag.com Git - debian/amanda/blob - xfer-src/xmsg.h

   1 /*
   2  * Copyright (c) 2008-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 as published
   6  * by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  10  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  16  *
  17  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 #ifndef XMSG_H
  22 #define XMSG_H
  23
  24 #include <glib.h>
  25 #include "xfer-element.h"
  26
  27 /* This module handles transmission of discrete messages from transfer
  28  * elements to the transfer master.  Messages have:
  29  *   an overall type (xmsg_msg_type)
  30  *   a version number
  31  *   a source (an XferElement)
  32  *   a number of attributes containing the message data
  33  *
  34  * Extensions to the protocol may add key/value pairs at any time without
  35  * affecting old implementations (that is, it is never an error to ignore
  36  * an unrecognized key).  Changes to the meaning of, or removal of,
  37  * existing keys from a message requires a version increment, which will
  38  * preclude older implementations from processing the message.  External
  39  * measures (such as amfeatures) should be employed in this case to ensure
  40  * backward compatibility.
  41  *
  42  * The implementation of messages is intended to sacrifice memory consumption
  43  * for speed and serializability.  Relatively few messages will exist at any
  44  * one time, but over the course of a dump, many messages will be created,
  45  * serialized, unserialized, and processed.
  46  */
  47
  48 /*
  49  * Message types
  50  */
  51
  52 /* N.B. -- when adding new message types, add the corresponding case label
  53  * to xfer-src/xmsg.c:xmsg_repr() and perl/Amanda/Xfer.swg */
  54 typedef enum {
  55     /* XMSG_INFO: informational messages suitable for display to user. Attributes:
  56      *  - message
  57      */
  58     XMSG_INFO = 1,
  59
  60     /* XMSG_ERROR: error message from an element.  Attributes:
  61      *  - message
  62      */
  63     XMSG_ERROR = 2,
  64
  65     /* XMSG_DONE: the transfer is done.  Only one XMSG_DONE message will be
  66      * delivered, when all elements are finished.
  67      * Attributes:
  68      *  (none)
  69      */
  70     XMSG_DONE = 3,
  71
  72     /* XMSG_CANCEL: this transfer is being cancelled, but data may still be
  73      * "draining" from buffers.  A subsequent XMSG_DONE indicates that the
  74      * transfer has actually completed.
  75      * Attributes:
  76      *  (none)
  77      */
  78     XMSG_CANCEL = 4,
  79
  80     /* XMSG_PART_DONE: a split part is finished; used by XferDestTaper and
  81      * XferSourceTaper elements to indicate that the element is paused and
  82      * awaiting instructions to start a new part.  Not all of the attributes
  83      * are applicable to both elements.
  84      *
  85      * Attributes:
  86      *  - successful (true if the whole part was written; always false for
  87      *          XferSourceTaper)
  88      *  - eom (true if the device is at EOM; always false for XferSourceTaper)
  89      *  - eof (recipient should not call start_part; always false for
  90      *          XferSourceTaper)
  91      *  - size (bytes written to or read from the volume)
  92      *  - duration (time spent writing, not counting changer ops, etc.)
  93      *  - partnum (the zero-based number of this part in the overall
  94      *          dumpfile; always 0 for XferSourceTaper)
  95      *  - fileno (the on-media file number used for this part, or 0 if no file
  96      *            was used)
  97      */
  98     XMSG_PART_DONE = 5,
  99
 100     /* XMSG_READY: some elements do some additional, potentially long-term
 101      * startup operations after the xfer itself starts.  This message is used
 102      * to indicate that the startup was successful.
 103      *
 104      * Attributes:
 105      *  (none)
 106      */
 107     XMSG_READY = 6,
 108 } xmsg_type;
 109
 110 /*
 111  * Class Declaration
 112  */
 113
 114 typedef struct XMsg {
 115     /* General header information */
 116
 117     /* the origin of the message */
 118     struct XferElement *elt;
 119
 120     /* the message's overall type */
 121     xmsg_type type;
 122
 123     /* the message's version number */
 124     int version;
 125
 126     /* internal use only; use xmsg_repr() to get the representation */
 127     char *repr;
 128
 129     /* Attributes. Many of these will be zero or null.  See the xmsg_type
 130      * enumeration for a description of the attributes that are set for each
 131      * message type.
 132      *
 133      * Note that any pointer-based attributes (strings, etc.) become owned
 134      * by the XMsg object, and will be freed in xmsg_free.  The use of stralloc()
 135      * is advised for strings.
 136      *
 137      * NOTE TO IMPLEMENTERS:
 138      *
 139      * When adding a new attribute, make changes in the following places:
 140      *  - add the attribute to the XMsg struct in xmsg.h
 141      *  - add the attribute to the comments for the appropriate xmsg_types
 142      *  - free the attribute in xmsg_free.
 143      *  - edit perl/Amanda/Xfer.swg:new_sv_for_xmsg
 144      */
 145
 146     /* free-form string message for display to the users
 147      *
 148      * This string is always valid UTF-8.  If it contains pathnames from a
 149      * bytestring-based filesystem, then non-ASCII bytes will be encoded using
 150      * quoted-printable.
 151      */
 152     char *message;
 153
 154     /* true indicates a successful operation */
 155     gboolean successful;
 156
 157     /* true if an EOM condition has occurred */
 158     gboolean eom;
 159
 160     /* true if an EOF condition has occurred */
 161     gboolean eof;
 162
 163     /* size, in bytes */
 164     guint64 size;
 165
 166     /* duration, in seconds */
 167     double duration;
 168
 169     /* split-part number */
 170     guint64 partnum;
 171
 172     /* file number on a volume */
 173     guint64 fileno;
 174 } XMsg;
 175
 176 /*
 177  * Methods
 178  */
 179
 180 /* Create a new XMsg.
 181  *
 182  * @param elt: element originating this message
 183  * @param type: message type
 184  * @param version: message version
 185  * @return: a new XMsg.
 186  */
 187 XMsg *xmsg_new(
 188     XferElement *elt,
 189     xmsg_type type,
 190     int version);
 191
 192 /* Free all memory associated with an XMsg.
 193  *
 194  * @param msg: the XMsg
 195  */
 196 void xmsg_free(XMsg *msg);
 197
 198 /* Return a printable representation of an XMsg.  This representation
 199  * is stored with the message, and will be freed when the message is
 200  * freed.
 201  *
 202  * @param msg: the XMsg
 203  * @return: string representation
 204  */
 205 char *xmsg_repr(XMsg *msg);
 206
 207 #endif