2 * Copyright (c) 2008 Zmanda, Inc. All Rights Reserved.
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.
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.
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.
17 * Contact information: Zmanda Inc., 465 S Mathlida Ave, Suite 300
18 * Sunnyvale, CA 94086, USA, or: http://www.zmanda.com
25 #include "xfer-element.h"
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)
31 * a source (an XferElement)
32 * a number of attributes containing the message data
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.
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.
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 */
55 /* XMSG_INFO: informational messages suitable for display to user. Attributes:
60 /* XMSG_ERROR: error message from an element. Attributes:
65 /* XMSG_DONE: the transfer is done. Only one XMSG_DONE message will be
66 * delivered, when all elements are finished.
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.
85 /* General header information */
87 /* the origin of the message */
88 struct XferElement *elt;
90 /* the message's overall type */
93 /* the message's version number */
96 /* internal use only; use xmsg_repr() to get the representation */
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
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.
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. */
110 /* free-form string message for display to the users
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
123 /* Create a new XMsg.
125 * @param elt: element originating this message
126 * @param type: message type
127 * @param version: message version
128 * @return: a new XMsg.
135 /* Free all memory associated with an XMsg.
137 * @param msg: the XMsg
139 void xmsg_free(XMsg *msg);
141 /* Return a printable representation of an XMsg. This representation
142 * is stored with the message, and will be freed when the message is
145 * @param msg: the XMsg
146 * @return: string representation
148 char *xmsg_repr(XMsg *msg);