LP#1729610: return new OpenSRF status if backlog queue fills up
[OpenSRF.git] / 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