1. Changes to comments and white space.

2. Eliminated the macro OSRF_MAX_PARAMS, which is nowhere used.  It was
all but unusable anyway, since it included a terminal semicolon.

I considered eliminating the macro OSRF_XML_NAMESPACE as well, since
it is also unused.  However I stayed my hand, since it would be more
difficult to reconstruct if the need arose.

M    include/opensrf/osrf_message.h
M    src/libopensrf/osrf_message.c

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

diff --git a/include/opensrf/osrf_message.h b/include/opensrf/osrf_message.h
index d9255ce..cd86e59 100644 (file)
--- a/include/opensrf/osrf_message.h
+++ b/include/opensrf/osrf_message.h
@@ -4,6 +4,21 @@
 /**
        @file osrf_message.h
        @brief Header for osrfMessage
+
+       An osrfMessage is the in-memory representation of a message between applications.
+
+       For transmission, one or more messages are encoded in a JSON array and wrapped in a
+       transport_message, which (together with its JSON cargo) is translated into XML as
+       a Jabber message.
+
+       There are five kinds of messages:
+       - CONNECT -- request to establish a stateful session.
+       - DISCONNECT -- ends a stateful session.
+       - REQUEST -- a remote procedure call.
+       - RESULT -- data returned by a remote procedure call.
+       - STATUS -- reports the success or failure of a requested operation.
+
+       Different kinds of messages use different combinations of the members of an osrfMessage.
 */
 
 #include <opensrf/string_array.h>
@@ -17,65 +32,72 @@ extern "C" {
 
 #define OSRF_XML_NAMESPACE "http://open-ils.org/xml/namespaces/oils_v1"
 
-#define OSRF_STATUS_CONTINUE                                           100
+#define OSRF_STATUS_CONTINUE             100
 
-#define OSRF_STATUS_OK                                                         200
-#define OSRF_STATUS_ACCEPTED                                           202
-#define OSRF_STATUS_COMPLETE                                           205
+#define OSRF_STATUS_OK                   200
+#define OSRF_STATUS_ACCEPTED             202
+#define OSRF_STATUS_COMPLETE             205
 
-#define OSRF_STATUS_REDIRECTED                                 307
+#define OSRF_STATUS_REDIRECTED           307
 
-#define OSRF_STATUS_BADREQUEST                                 400
-#define OSRF_STATUS_UNAUTHORIZED                                       401
-#define OSRF_STATUS_FORBIDDEN                                          403
-#define OSRF_STATUS_NOTFOUND                                           404
-#define OSRF_STATUS_NOTALLOWED                                 405
-#define OSRF_STATUS_TIMEOUT                                            408
-#define OSRF_STATUS_EXPFAILED                                          417
+#define OSRF_STATUS_BADREQUEST           400
+#define OSRF_STATUS_UNAUTHORIZED         401
+#define OSRF_STATUS_FORBIDDEN            403
+#define OSRF_STATUS_NOTFOUND             404
+#define OSRF_STATUS_NOTALLOWED           405
+#define OSRF_STATUS_TIMEOUT              408
+#define OSRF_STATUS_EXPFAILED            417
 
-#define OSRF_STATUS_INTERNALSERVERERROR                500
-#define OSRF_STATUS_NOTIMPLEMENTED                             501
-#define OSRF_STATUS_VERSIONNOTSUPPORTED                505
+#define OSRF_STATUS_INTERNALSERVERERROR  500
+#define OSRF_STATUS_NOTIMPLEMENTED       501
+#define OSRF_STATUS_VERSIONNOTSUPPORTED  505
 
 
 enum M_TYPE { CONNECT, REQUEST, RESULT, STATUS, DISCONNECT };
 
-#define OSRF_MAX_PARAMS                                                                128;
-
 struct osrf_message_struct {
 
+       /** One of the four message types: CONNECT, REQUEST, RESULT, STATUS, or DISCONNECT. */
        enum M_TYPE m_type;
+       
+       /** Used to keep track of which responses go with which requests. */
        int thread_trace;
+       
+       /** Currently serves no discernible purpose, but may be useful someday. */
        int protocol;
 
-       /* if we're a STATUS message */
+       /** Used for STATUS or RESULT messages. */
        char* status_name;
 
-       /* if we're a STATUS or RESULT */
+       /** Used for STATUS or RESULT messages. */
        char* status_text;
+
+       /** Used for STATUS or RESULT messages. */
        int status_code;
 
+       /** Boolean: true for some kinds of error conditions. */
        int is_exception;
 
-       /* if we're a RESULT */
+       /** Used for RESULT messages: contains the data returned by a remote procedure. */
        jsonObject* _result_content;
 
-       /* unparsed json string */
+       /** Unparsed JSON string containing the data returned by a remote procedure.
+       Unused and useless. */
        char* result_string;
 
-       /* if we're a REQUEST */
+       /** For a REQUEST message: name of the remote procedure to call. */
        char* method_name;
 
+       /** For a REQUEST message: parameters to pass to the remote procedure call. */
        jsonObject* _params;
 
-       /* in case anyone wants to make a list of us.  
-               we won't touch this variable */
+       /** Pointer for linked lists.  Used only by calling code. */
        struct osrf_message_struct* next;
 
-       /* magical LOCALE hint */
+       /** Magical LOCALE hint. */
        char* sender_locale;
 
-       /* timezone offset from GMT of sender, in seconds */
+       /** Timezone offset from GMT of sender, in seconds.  Not used. */
        int sender_tz_offset;
 
 };

diff --git a/src/libopensrf/osrf_message.c b/src/libopensrf/osrf_message.c
index c5f8644..b1f7d4e 100644 (file)
--- a/src/libopensrf/osrf_message.c
+++ b/src/libopensrf/osrf_message.c
@@ -1,4 +1,3 @@
-
 /**
        @file osrf_message.c
        @brief Implementation of osrfMessage.
@@ -439,7 +438,7 @@ static jsonObject* osrfMessageToJSON( const osrfMessage* msg ) {
 /**
        @brief Translate a JSON array into an osrfList of osrfMessages.
        @param string The JSON string to be translated.
-       @param msgs Pointer to an osrfList (may be NULL)
+       @param list Pointer to an osrfList of osrfMessages (may be NULL)
        @return Pointer to an osrfList containing pointers to osrfMessages.
 
        The JSON string is expected to be a JSON array, with each element encoding an osrfMessage.