include/opensrf/osrf_message.h

   1 #ifndef osrf_message_h
   2 #define osrf_message_h
   3
   4 /**
   5         @file osrf_message.h
   6         @brief Header for osrfMessage
   7
   8         An osrfMessage is the in-memory representation of a message between applications.
   9
  10         For transmission, one or more messages are encoded in a JSON array and wrapped in a
  11         transport_message, which (together with its JSON cargo) is translated into XML as
  12         a Jabber message.
  13
  14         There are five kinds of messages:
  15         - CONNECT -- request to establish a stateful session.
  16         - DISCONNECT -- ends a stateful session.
  17         - REQUEST -- a remote procedure call.
  18         - RESULT -- data returned by a remote procedure call.
  19         - STATUS -- reports the success or failure of a requested operation.
  20
  21         Different kinds of messages use different combinations of the members of an osrfMessage.
  22 */
  23
  24 #include <opensrf/string_array.h>
  25 #include <opensrf/utils.h>
  26 #include <opensrf/log.h>
  27 #include <opensrf/osrf_json.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #define OSRF_XML_NAMESPACE "http://open-ils.org/xml/namespaces/oils_v1"
  34
  35 #define OSRF_STATUS_CONTINUE             100
  36
  37 #define OSRF_STATUS_OK                   200
  38 #define OSRF_STATUS_ACCEPTED             202
  39 #define OSRF_STATUS_COMPLETE             205
  40
  41 #define OSRF_STATUS_PARTIAL              206
  42 #define OSRF_STATUS_NOCONTENT            204
  43
  44 #define OSRF_STATUS_REDIRECTED           307
  45
  46 #define OSRF_STATUS_BADREQUEST           400
  47 #define OSRF_STATUS_UNAUTHORIZED         401
  48 #define OSRF_STATUS_FORBIDDEN            403
  49 #define OSRF_STATUS_NOTFOUND             404
  50 #define OSRF_STATUS_NOTALLOWED           405
  51 #define OSRF_STATUS_TIMEOUT              408
  52 #define OSRF_STATUS_EXPFAILED            417
  53
  54 #define OSRF_STATUS_INTERNALSERVERERROR  500
  55 #define OSRF_STATUS_NOTIMPLEMENTED       501
  56 #define OSRF_STATUS_SERVICEUNAVAILABLE   503
  57 #define OSRF_STATUS_VERSIONNOTSUPPORTED  505
  58
  59
  60 enum M_TYPE { CONNECT, REQUEST, RESULT, STATUS, DISCONNECT };
  61
  62 struct osrf_message_struct {
  63
  64         /** One of the four message types: CONNECT, REQUEST, RESULT, STATUS, or DISCONNECT. */
  65         enum M_TYPE m_type;
  66
  67         /** Used to keep track of which responses go with which requests. */
  68         int thread_trace;
  69
  70         /** Currently serves no discernible purpose, but may be useful someday. */
  71         int protocol;
  72
  73         /** Used for STATUS or RESULT messages. */
  74         char* status_name;
  75
  76         /** Used for STATUS or RESULT messages. */
  77         char* status_text;
  78
  79         /** Used for STATUS or RESULT messages. */
  80         int status_code;
  81
  82         /** Boolean: true for some kinds of error conditions. */
  83         int is_exception;
  84
  85         /** Used for RESULT messages: contains the data returned by a remote procedure. */
  86         jsonObject* _result_content;
  87
  88         /** For a REQUEST message: name of the remote procedure to call. */
  89         char* method_name;
  90
  91         /** For a REQUEST message: parameters to pass to the remote procedure call. */
  92         jsonObject* _params;
  93
  94         /** Pointer for linked lists.  Used only by calling code. */
  95         struct osrf_message_struct* next;
  96
  97         /** Magical LOCALE hint. */
  98         char* sender_locale;
  99
 100         /** Magical ingress hint. */
 101         char* sender_ingress;
 102
 103         /** Magical TZ hint. */
 104         char* sender_tz;
 105 };
 106 typedef struct osrf_message_struct osrfMessage;
 107
 108 const char* osrf_message_set_locale( osrfMessage* msg, const char* locale );
 109
 110 const char* osrf_message_set_tz( osrfMessage* msg, const char* tz );
 111
 112 const char* osrfMessageSetIngress( osrfMessage* msg, const char* ingress );
 113
 114 const char* osrf_message_set_default_locale( const char* locale );
 115
 116 const char* osrf_message_get_last_locale(void);
 117
 118 const char* osrf_message_get_last_tz(void);
 119
 120 osrfMessage* osrf_message_init( enum M_TYPE type, int thread_trace, int protocol );
 121
 122 void osrf_message_set_status_info( osrfMessage*,
 123                 const char* status_name, const char* status_text, int status_code );
 124
 125 void osrf_message_set_result_content( osrfMessage*, const char* json_string );
 126
 127 void osrf_message_set_result( osrfMessage* msg, const jsonObject* obj );
 128
 129 void osrfMessageFree( osrfMessage* );
 130
 131 char* osrf_message_to_xml( osrfMessage* );
 132
 133 jsonObject* osrfMessageToJSON( const osrfMessage* msg );
 134
 135 char* osrf_message_serialize(const osrfMessage*);
 136
 137 osrfList* osrfMessageDeserialize( const char* string, osrfList* list );
 138
 139 int osrf_message_deserialize(const char* json, osrfMessage* msgs[], int count);
 140
 141 void osrf_message_set_params( osrfMessage* msg, const jsonObject* o );
 142
 143 void osrf_message_set_method( osrfMessage* msg, const char* method_name );
 144
 145 void osrf_message_add_object_param( osrfMessage* msg, const jsonObject* o );
 146
 147 void osrf_message_add_param( osrfMessage*, const char* param_string );
 148
 149 const jsonObject* osrfMessageGetResult( osrfMessage* msg );
 150
 151 char* osrfMessageSerializeBatch( osrfMessage* msgs [], int count );
 152
 153 #ifdef __cplusplus
 154 }
 155 #endif
 156
 157 #endif