[Opensrf-commits] r1830 - trunk/include/opensrf (scottmk)

[svn at svn.open-ils.org]

Author: scottmk
Date: 2009-10-29 15:25:39 -0400 (Thu, 29 Oct 2009)
New Revision: 1830

Modified:
   trunk/include/opensrf/transport_message.h
Log:
Add doxygen-style comments to document the
transport_message structure.

M    include/opensrf/transport_message.h


Modified: trunk/include/opensrf/transport_message.h
===================================================================
--- trunk/include/opensrf/transport_message.h	2009-10-29 18:02:48 UTC (rev 1829)
+++ trunk/include/opensrf/transport_message.h	2009-10-29 19:25:39 UTC (rev 1830)
@@ -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);