From ebbedc3d58580d240848d220c7e8df8481d2833f Mon Sep 17 00:00:00 2001 From: scottmk Date: Mon, 16 Nov 2009 03:53:18 +0000 Subject: [PATCH] 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 --- include/opensrf/osrf_message.h | 74 +++++++++++++++++++++++++++--------------- src/libopensrf/osrf_message.c | 3 +- 2 files changed, 49 insertions(+), 28 deletions(-) diff --git a/include/opensrf/osrf_message.h b/include/opensrf/osrf_message.h index d9255ce..cd86e59 100644 --- 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 @@ -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 --- 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. -- 2.11.0