2 * Copyright (c) 2008,2009 Zmanda, Inc. All Rights Reserved.
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.
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
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
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, 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.
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.
86 * - successful (true if the whole part was written; always false for
88 * - eom (true if the device is at EOM; always false for XferSourceTaper)
89 * - eof (recipient should not call start_part; always false for
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
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.
114 typedef struct XMsg {
115 /* General header information */
117 /* the origin of the message */
118 struct XferElement *elt;
120 /* the message's overall type */
123 /* the message's version number */
126 /* internal use only; use xmsg_repr() to get the representation */
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
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.
137 * NOTE TO IMPLEMENTERS:
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
146 /* free-form string message for display to the users
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
154 /* true indicates a successful operation */
157 /* true if an EOM condition has occurred */
160 /* true if an EOF condition has occurred */
166 /* duration, in seconds */
169 /* split-part number */
172 /* file number on a volume */
180 /* Create a new XMsg.
182 * @param elt: element originating this message
183 * @param type: message type
184 * @param version: message version
185 * @return: a new XMsg.
192 /* Free all memory associated with an XMsg.
194 * @param msg: the XMsg
196 void xmsg_free(XMsg *msg);
198 /* Return a printable representation of an XMsg. This representation
199 * is stored with the message, and will be freed when the message is
202 * @param msg: the XMsg
203 * @return: string representation
205 char *xmsg_repr(XMsg *msg);