Add doxygen-style comments to document the

transport_message structure.

M    include/opensrf/transport_message.h

git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1830 9efc2488-bf62-4759-914b-345cdb29e865

diff --git a/include/opensrf/transport_message.h b/include/opensrf/transport_message.h
index 5c1a4d6..fb43f92 100644 (file)
--- a/include/opensrf/transport_message.h
+++ b/include/opensrf/transport_message.h
@@ -1,6 +1,14 @@
 #ifndef TRANSPORT_MESSAGE_H
 #define TRANSPORT_MESSAGE_H
 
+/**
+       @file transport_message.h
+       @brief Header for routines to manage transport_messages.
+
+       A transport_message is a representation of a Jabber message. i.e. a message stanza in a
+       Jabber XML stream.
+*/
+
 #include <string.h>
 #include <libxml/globals.h>
 #include <libxml/xmlerror.h>
@@ -17,72 +25,58 @@
 extern "C" {
 #endif
 
-// ---------------------------------------------------------------------------------
-// Jabber message object.
-// ---------------------------------------------------------------------------------
+/**
+       @brief A representation of a Jabber message.
+
+       A transport_message represents a message stanza of a Jabber XML stream.  The various
+       members store the contents of various attributes or text in the XML.  The following
+       members represent OSRF extensions:
+       - router_from
+       - router_to
+       - router_class
+       - router_command
+       - osrf_xid
+       - broadcast
+*/
 struct transport_message_struct {
-       char* body;
-       char* subject;
-       char* thread;
-       char* recipient;
-       char* sender;
-       char* router_from;
-       char* router_to;
-       char* router_class;
-       char* router_command;
-       char* osrf_xid;
-       int is_error;
-       char* error_type;
-       int error_code;
-       int broadcast;
-       char* msg_xml; /* the entire message as XML complete with entity encoding */
+       char* body;            /**< Text enclosed by the body element. */
+       char* subject;         /**< Text enclosed by the subject element. */
+       char* thread;          /**< Text enclosed by the thread element. */
+       char* recipient;       /**< Value of the "to" attribute in the message element. */
+       char* sender;          /**< Value of the "from" attribute in the message element. */
+       char* router_from;     /**< Value of the "router_from" attribute in the message element. */
+       char* router_to;       /**< Value of the "router_to" attribute in the message element. */
+       char* router_class;    /**< Value of the "router_class" attribute in the message element. */
+       char* router_command;  /**< Value of the "router_command" attribute in the message element. */
+       char* osrf_xid;        /**< Value of the "osrf_xid" attribute in the message element. */
+       int is_error;          /**< Boolean; true if &lt;error&gt; is present. */
+       char* error_type;      /**< Value of the "type" attribute of &lt;error&gt;. */
+       int error_code;        /**< Value of the "code" attribute of &lt;error&gt;. */
+       int broadcast;         /**< Value of the "broadcast" attribute in the message element. */
+       char* msg_xml;         /**< The entire message as XML, complete with entity encoding. */
        struct transport_message_struct* next;
 };
 typedef struct transport_message_struct transport_message;
 
-// ---------------------------------------------------------------------------------
-// Allocates and returns a transport_message.  All chars are safely re-allocated
-// within this method.
-// Returns NULL on error
-// ---------------------------------------------------------------------------------
-transport_message* message_init( const char* body, const char* subject, 
+transport_message* message_init( const char* body, const char* subject,
                const char* thread, const char* recipient, const char* sender );
 
 transport_message* new_message_from_xml( const char* msg_xml );
 
-
 void message_set_router_info( transport_message* msg, const char* router_from,
                const char* router_to, const char* router_class, const char* router_command,
                int broadcast_enabled );
 
 void message_set_osrf_xid( transport_message* msg, const char* osrf_xid );
 
-// ---------------------------------------------------------------------------------
-// Call this to create the encoded XML for sending on the wire.
-// This is a seperate function so that encoding will not necessarily have
-// to happen on all messages (i.e. typically only occurs outbound messages).
-// ---------------------------------------------------------------------------------
 int message_prepare_xml( transport_message* msg );
 
-// ---------------------------------------------------------------------------------
-// Deallocates the memory used by the transport_message
-// Returns 0 on error
-// ---------------------------------------------------------------------------------
 int message_free( transport_message* msg );
 
-// ---------------------------------------------------------------------------------
-// Determines the username of a Jabber ID.  This expects a pre-allocated char 
-// array for the return value.
-// ---------------------------------------------------------------------------------
 void jid_get_username( const char* jid, char buf[], int size );
 
-// ---------------------------------------------------------------------------------
-// Determines the resource of a Jabber ID.  This expects a pre-allocated char 
-// array for the return value.
-// ---------------------------------------------------------------------------------
 void jid_get_resource( const char* jid, char buf[], int size );
 
-/** Puts the domain portion of the given jid into the pre-allocated buffer */
 void jid_get_domain( const char* jid, char buf[], int size );
 
 void set_msg_error( transport_message*, const char* error_type, int error_code);