From 79c6271be2c91fc65014cfb3df6a52fb65dd3251 Mon Sep 17 00:00:00 2001 From: scottmk Date: Thu, 29 Oct 2009 19:25:39 +0000 Subject: [PATCH 1/1] 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 --- include/opensrf/transport_message.h | 80 +++++++++++++---------------- 1 file changed, 37 insertions(+), 43 deletions(-) diff --git a/include/opensrf/transport_message.h b/include/opensrf/transport_message.h index 5c1a4d6..fb43f92 100644 --- 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 #include #include @@ -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 <error> is present. */ + char* error_type; /**< Value of the "type" attribute of <error>. */ + int error_code; /**< Value of the "code" attribute of <error>. */ + 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); -- 2.43.2