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

   1 /*
   2  * Copyright (c) 2008 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License version 2.1 as
   6  * published by the Free Software Foundation.
   7  *
   8  * This library 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 Lesser General Public
  11  * License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA.
  16  *
  17  * Contact information: Zmanda Inc., 465 S Mathlida Ave, Suite 300
  18  * Sunnyvale, CA 94086, 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      */
  76     XMSG_CANCEL = 4,
  77
  78 } xmsg_type;
  79
  80 /*
  81  * Class Declaration
  82  */
  83
  84 typedef struct XMsg {
  85     /* General header information */
  86
  87     /* the origin of the message */
  88     struct XferElement *elt;
  89
  90     /* the message's overall type */
  91     xmsg_type type;
  92
  93     /* the message's version number */
  94     int version;
  95
  96     /* internal use only; use xmsg_repr() to get the representation */
  97     char *repr;
  98
  99     /* Attributes. Many of these will be zero or null.  See the xmsg_type
 100      * enumeration for a description of the attributes that are set for each
 101      * message type.
 102      *
 103      * Note that any pointer-based attributes (strings, etc.) become owned
 104      * by the XMsg object, and will be freed in xmsg_free.  The use of stralloc()
 105      * is advised for strings.
 106      *
 107      * N.B. When adding new attributes, also edit perl/Amanda/Xfer.swg:xmsg_to_sv
 108      * so that they will be accessible from Perl. */
 109
 110     /* free-form string message for display to the users
 111      *
 112      * This string is always valid UTF-8.  If it contains pathnames from a
 113      * bytestring-based filesystem, then non-ASCII bytes will be encoded using
 114      * quoted-printable.
 115      */
 116     char *message;
 117 } XMsg;
 118
 119 /*
 120  * Methods
 121  */
 122
 123 /* Create a new XMsg.
 124  *
 125  * @param elt: element originating this message
 126  * @param type: message type
 127  * @param version: message version
 128  * @return: a new XMsg.
 129  */
 130 XMsg *xmsg_new(
 131     XferElement *elt,
 132     xmsg_type type,
 133     int version);
 134
 135 /* Free all memory associated with an XMsg.
 136  *
 137  * @param msg: the XMsg
 138  */
 139 void xmsg_free(XMsg *msg);
 140
 141 /* Return a printable representation of an XMsg.  This representation
 142  * is stored with the message, and will be freed when the message is
 143  * freed.
 144  *
 145  * @param msg: the XMsg
 146  * @return: string representation
 147  */
 148 char *xmsg_repr(XMsg *msg);
 149
 150 #endif