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