Tidied up various things:
[OpenSRF.git] / src / libopensrf / osrf_message.c
1 #include <opensrf/osrf_message.h>
2
3 /**
4         @file osrf_message.c
5         @brief Implementation of osrfMessage.
6 */
7
8 static jsonObject* osrfMessageToJSON( const osrfMessage* msg );
9
10 static char default_locale[17] = "en-US\0\0\0\0\0\0\0\0\0\0\0\0";
11 static char* current_locale = NULL;
12
13 /**
14         @brief Allocate and initialize an osrfMessage.
15         @param type One of CONNECT, REQUEST, RESULT, STATUS, or DISCONNECT.
16         @param thread_trace Thread trace.
17         @param protocol Protocol.
18         @return Pointer to the newly allocated osrfMessage.
19
20         The calling code is responsible for freeing the osrfMessage by calling osrfMessageFree().
21 */
22 osrfMessage* osrf_message_init( enum M_TYPE type, int thread_trace, int protocol ) {
23
24         osrfMessage* msg            = (osrfMessage*) safe_malloc(sizeof(osrfMessage));
25         msg->m_type                 = type;
26         msg->thread_trace           = thread_trace;
27         msg->protocol               = protocol;
28         msg->status_name            = NULL;
29         msg->status_text            = NULL;
30         msg->status_code            = 0;
31         msg->next                   = NULL;
32         msg->is_exception           = 0;
33         msg->_params                = NULL;
34         msg->_result_content        = NULL;
35         msg->result_string          = NULL;
36         msg->method_name            = NULL;
37         msg->sender_locale          = NULL;
38         msg->sender_tz_offset       = 0;
39
40         return msg;
41 }
42
43
44 /**
45         @brief Return the previous locale.
46         @return A pointer to the locale specified by the last message to have been deserialized,
47                 or NULL.
48
49         A JSON message may specify a locale string, which is saved as the current locale.  If
50         the message does not specify a locale string, then the current locale becomes NULL.
51
52         This function returns a pointer to an internal buffer.  Since both the address and the
53         contents of this buffer may change from one call to the next, the calling code should
54         either use the result immediately or make a copy of the string for later use.
55 */
56 const char* osrf_message_get_last_locale() {
57         return current_locale;
58 }
59
60 /**
61         @brief Set the locale for a specified osrfMessage.
62         @param msg Pointer to the osrfMessage.
63         @param locale Pointer to the locale string to be installed in the osrfMessage.
64         @return Pointer to the new locale string for the osrfMessage, or NULL if either
65                 parameter is NULL.
66
67         If no locale is specified for an osrfMessage, we use the default locale.
68
69         Used for a REQUEST message.
70 */
71 const char* osrf_message_set_locale( osrfMessage* msg, const char* locale ) {
72         if( msg == NULL || locale == NULL )
73                 return NULL;
74         if( msg->sender_locale )
75                 free( msg->sender_locale );
76         return msg->sender_locale = strdup( locale );
77 }
78
79 /**
80         @brief Change the default locale.
81         @param locale The new default locale.
82         @return A pointer to the new default locale if successful, or NULL if not.
83
84         The function returns NULL if the parameter is NULL, or if the proposed new locale is
85         longer than 16 characters.
86
87         At this writing, nothing calls this function.
88 */
89 const char* osrf_message_set_default_locale( const char* locale ) {
90         if( locale == NULL ) return NULL;
91         if( strlen(locale) > sizeof(default_locale) - 1 ) return NULL;
92
93         strcpy( default_locale, locale );
94         return default_locale;
95 }
96
97 /**
98         @brief Populate the method_name member of an osrfMessage.
99         @param msg Pointer to the osrfMessage.
100         @param method_name The method name.
101
102         Used for a REQUEST message to specify what method to invoke.
103 */
104 void osrf_message_set_method( osrfMessage* msg, const char* method_name ) {
105         if( msg == NULL || method_name == NULL )
106                 return;
107         if( msg->method_name )
108                 free( msg->method_name );
109         msg->method_name = strdup( method_name );
110 }
111
112
113 /**
114         @brief Add a copy of a jsonObject to an osrfMessage as a parameter for a method call.
115         @param msg Pointer to the osrfMessage.
116         @param o Pointer to the jsonObject of which a copy is to be stored.
117
118         Make a copy of the input jsonObject, with all classnames encoded with JSON_CLASS_KEY and
119         JSON_DATA_KEY.  Append it to a JSON_ARRAY stored at msg->_params.
120
121         If there is nothing at msg->_params, create a new JSON_ARRAY for it and add the new object
122         as the first element.
123
124         If the jsonObject is raw (i.e. the class information has not been decoded into classnames),
125         decode it.  If the class information has already been decoded, discard it.
126
127         See also osrf_message_add_param().
128
129         At this writing, nothing calls this function.
130 */
131 void osrf_message_add_object_param( osrfMessage* msg, const jsonObject* o ) {
132         if(!msg|| !o) return;
133         if(!msg->_params)
134                 msg->_params = jsonNewObjectType( JSON_ARRAY );
135         jsonObjectPush(msg->_params, jsonObjectDecodeClass( o ));
136 }
137
138 /**
139         @brief Populate the params member of an osrfMessage.
140         @param msg Pointer to the osrfMessage.
141         @param o Pointer to a jsonObject representing the parameter(s) to a method.
142
143         Make a copy of a jsonObject and install it as the parameter list for a method call.
144
145         If the osrfMessage already has any parameters, discard them.
146
147         The @a o parameter should point to a jsonObject of type JSON_ARRAY, with each element
148         of the array being a parameter.  If @a o points to any other type of jsonObject, create
149         a JSON_ARRAY as a wrapper for it, and install a copy of @a o as its only element.
150
151         Used for a REQUEST message, to pass parameters to a method.  The alternative is to call
152         osrf_message_add_param() or osrf_message_add_object_param() repeatedly as needed to add
153         one parameter at a time.
154 */
155 void osrf_message_set_params( osrfMessage* msg, const jsonObject* o ) {
156         if(!msg || !o) return;
157
158         if(msg->_params)
159                 jsonObjectFree(msg->_params);
160
161         if(o->type == JSON_ARRAY) {
162                 msg->_params = jsonObjectClone(o);
163         } else {
164                 osrfLogDebug( OSRF_LOG_MARK, "passing non-array to osrf_message_set_params(), fixing...");
165                 jsonObject* clone = jsonObjectClone(o);
166                 msg->_params = jsonNewObjectType( JSON_ARRAY );
167                 jsonObjectPush(msg->_params, clone);
168                 return;
169         }
170 }
171
172
173 /**
174         @brief Add a JSON string to an osrfMessage as a parameter for a method call.
175         @param msg Pointer to the osrfMessage.
176         @param param_string A JSON string encoding the parameter to be added.
177
178         Translate the JSON string into a jsonObject, and append it to the parameter list.
179         If the parameter list doesn't already exist, create an empty one and add the new
180         parameter to it.
181
182         Decode any class information in the raw JSON into classnames.
183
184         If the JSON string is not valid JSON, append a new jsonObject of type JSON_NULL.
185
186         Used for a REQUEST message, to pass a parameter to a method,  The alternative is to
187         call osrf_message_set_params() to provide all the parameters at once.  See also
188         osrf_message_add_object_param().
189 */
190 void osrf_message_add_param( osrfMessage* msg, const char* param_string ) {
191         if(msg == NULL || param_string == NULL) return;
192         if(!msg->_params) msg->_params = jsonNewObjectType( JSON_ARRAY );
193         jsonObjectPush(msg->_params, jsonParseString(param_string));
194 }
195
196
197 /**
198         @brief Set the status_name, status_text, and status_code members of an osrfMessage.
199         @param msg Pointer to the osrfMessage to be populated.
200         @param status_name Status name (may be NULL).
201         @param status_text Status text (may be NULL).
202         @param status_code Status code.
203
204         If the @a status_name or @a status_text parameter is NULL, the corresponding member
205         is left unchanged.
206
207         Used for a RESULT or STATUS message.
208 */
209 void osrf_message_set_status_info( osrfMessage* msg,
210                 const char* status_name, const char* status_text, int status_code ) {
211         if(!msg) return;
212
213         if( status_name != NULL ) {
214                 if( msg->status_name )
215                         free( msg->status_name );
216                 msg->status_name = strdup( status_name );
217         }
218
219         if( status_text != NULL ) {
220                 if( msg->status_text )
221                         free( msg->status_text );
222                 msg->status_text = strdup( status_text );
223         }
224
225         msg->status_code = status_code;
226 }
227
228
229 /**
230         @brief Populate the result_string and _result_content members of an osrfMessage.
231         @param msg Pointer to the osrfMessage to be populated.
232         @param json_string A JSON string encoding a result set.
233
234         Used for a RESULT message to return the results of a request, such as a database lookup.
235 */
236 void osrf_message_set_result_content( osrfMessage* msg, const char* json_string ) {
237         if( msg == NULL || json_string == NULL) return;
238         if( msg->result_string )
239                 free( msg->result_string );
240         if( msg->_result_content )
241                 jsonObjectFree( msg->_result_content );
242
243         msg->result_string   = strdup(json_string);
244         msg->_result_content = jsonParseString(json_string);
245 }
246
247
248 /**
249         @brief Free an osrfMessage and everything it owns.
250         @param msg Pointer to the osrfMessage to be freed.
251 */
252 void osrfMessageFree( osrfMessage* msg ) {
253         if( msg == NULL )
254                 return;
255
256         if( msg->status_name != NULL )
257                 free(msg->status_name);
258
259         if( msg->status_text != NULL )
260                 free(msg->status_text);
261
262         if( msg->_result_content != NULL )
263                 jsonObjectFree( msg->_result_content );
264
265         if( msg->result_string != NULL )
266                 free( msg->result_string);
267
268         if( msg->method_name != NULL )
269                 free(msg->method_name);
270
271         if( msg->sender_locale != NULL )
272                 free(msg->sender_locale);
273
274         if( msg->_params != NULL )
275                 jsonObjectFree(msg->_params);
276
277         free(msg);
278 }
279
280
281 /**
282         @brief Turn a collection of osrfMessages into one big JSON string.
283         @param msgs Pointer to an array of osrfMessages.
284         @param count Maximum number of messages to serialize.
285         @return Pointer to the JSON string.
286
287         Traverse the array, adding each osrfMessage in turn to a JSON_ARRAY.  Stop when you have added the
288         maximum number of messages, or when you encounter a NULL pointer in the array.  Then translate the
289         JSON_ARRAY into a JSON string.
290
291         The calling code is responsible for freeing the returned string.
292 */
293 char* osrfMessageSerializeBatch( osrfMessage* msgs [], int count ) {
294         if( !msgs ) return NULL;
295
296         jsonObject* wrapper = jsonNewObjectType(JSON_ARRAY);
297
298         int i = 0;
299         while( (i < count) && msgs[i] ) {
300                 jsonObjectPush(wrapper, osrfMessageToJSON( msgs[i] ));
301                 ++i;
302         }
303
304         char* j = jsonObjectToJSON(wrapper);
305         jsonObjectFree(wrapper);
306
307         return j;
308 }
309
310
311 /**
312         @brief Turn a single osrfMessage into a JSON string.
313         @param msg Pointer to the osrfMessage to be serialized.
314         @return Pointer to the resulting JSON string.
315
316         Translate the osrfMessage into JSON, wrapped in a JSON array.
317
318         This function is equivalent to osrfMessageSerializeBatch() for an array of one pointer.
319
320         The calling code is responsible for freeing the returned string.
321 */
322 char* osrf_message_serialize(const osrfMessage* msg) {
323
324         if( msg == NULL ) return NULL;
325         char* j = NULL;
326
327         jsonObject* json = osrfMessageToJSON( msg );
328
329         if(json) {
330                 jsonObject* wrapper = jsonNewObjectType(JSON_ARRAY);
331                 jsonObjectPush(wrapper, json);
332                 j = jsonObjectToJSON(wrapper);
333                 jsonObjectFree(wrapper);
334         }
335
336         return j;
337 }
338
339
340 /**
341         @brief Translate an osrfMessage into a jsonObject.
342         @param msg Pointer to the osrfMessage to be translated.
343         @return Pointer to a newly created jsonObject.
344
345         The resulting jsonObject is a JSON_HASH with a classname of "osrfMessage", and the following keys:
346         - "threadTrace"
347         - "locale"
348         - "type"
349         - "payload" (only for STATUS, REQUEST, and RESULT messages)
350
351         The data for "payload" is also a JSON_HASH, whose structure depends on the message type:
352
353         For a STATUS message, the payload's classname is msg->status_name.  The keys are "status" (carrying
354         msg->status_text) and "statusCode" (carrying the status code as a string).
355
356         For a REQUEST message, the payload's classname is "osrfMethod".  The keys are "method" (carrying
357         msg->method_name) and "params" (carrying a jsonObject to pass any parameters to the method call).
358
359         For a RESULT message, the payload's classname is "osrfResult".  The keys are "status" (carrying
360         msg->status_text), "statusCode" (carrying the status code as a string), and "content" (carrying a jsonObject 
361         to return any results from the method call).
362
363         The calling code is responsible for freeing the returned jsonObject.
364 */
365 static jsonObject* osrfMessageToJSON( const osrfMessage* msg ) {
366
367         jsonObject* json = jsonNewObjectType(JSON_HASH);
368         jsonObjectSetClass(json, "osrfMessage");
369         jsonObject* payload;
370         char sc[64];
371         osrf_clearbuf(sc, sizeof(sc));
372
373         INT_TO_STRING(msg->thread_trace);
374         jsonObjectSetKey(json, "threadTrace", jsonNewObject(INTSTR));
375
376         if (msg->sender_locale != NULL) {
377                 jsonObjectSetKey(json, "locale", jsonNewObject(msg->sender_locale));
378         } else if (current_locale != NULL) {
379                 jsonObjectSetKey(json, "locale", jsonNewObject(current_locale));
380         } else {
381                 jsonObjectSetKey(json, "locale", jsonNewObject(default_locale));
382         }
383
384         switch(msg->m_type) {
385
386                 case CONNECT:
387                         jsonObjectSetKey(json, "type", jsonNewObject("CONNECT"));
388                         break;
389
390                 case DISCONNECT:
391                         jsonObjectSetKey(json, "type", jsonNewObject("DISCONNECT"));
392                         break;
393
394                 case STATUS:
395                         jsonObjectSetKey(json, "type", jsonNewObject("STATUS"));
396                         payload = jsonNewObject(NULL);
397                         jsonObjectSetClass(payload, msg->status_name);
398                         jsonObjectSetKey(payload, "status", jsonNewObject(msg->status_text));
399                         snprintf(sc, sizeof(sc), "%d", msg->status_code);
400                         jsonObjectSetKey(payload, "statusCode", jsonNewObject(sc));
401                         jsonObjectSetKey(json, "payload", payload);
402                         break;
403
404                 case REQUEST:
405                         jsonObjectSetKey(json, "type", jsonNewObject("REQUEST"));
406                         payload = jsonNewObject(NULL);
407                         jsonObjectSetClass(payload, "osrfMethod");
408                         jsonObjectSetKey(payload, "method", jsonNewObject(msg->method_name));
409                         jsonObjectSetKey( payload, "params", jsonObjectDecodeClass( msg->_params ) );
410                         jsonObjectSetKey(json, "payload", payload);
411
412                         break;
413
414                 case RESULT:
415                         jsonObjectSetKey(json, "type", jsonNewObject("RESULT"));
416                         payload = jsonNewObject(NULL);
417                         jsonObjectSetClass(payload,"osrfResult");
418                         jsonObjectSetKey(payload, "status", jsonNewObject(msg->status_text));
419                         snprintf(sc, sizeof(sc), "%d", msg->status_code);
420                         jsonObjectSetKey(payload, "statusCode", jsonNewObject(sc));
421                         jsonObjectSetKey(payload, "content", jsonObjectDecodeClass( msg->_result_content ));
422                         jsonObjectSetKey(json, "payload", payload);
423                         break;
424         }
425
426         return json;
427 }
428
429
430 /**
431         @brief Translate a JSON array into an array of osrfMessages.
432         @param string The JSON string to be translated.
433         @param msgs Pointer to an array of pointers to osrfMessage, to receive the results.
434         @param count How many slots are available in the @a msgs array.
435         @return The number of osrfMessages created.
436
437         The JSON string is expected to be a JSON array, with each element encoding an osrfMessage.
438
439         If there are too many messages in the JSON array to fit into the pointer array, we
440         silently ignore the excess.
441 */
442 int osrf_message_deserialize(const char* string, osrfMessage* msgs[], int count) {
443
444         if(!string || !msgs || count <= 0) return 0;
445         int numparsed = 0;
446
447         // Parse the JSON
448         jsonObject* json = jsonParseString(string);
449
450         if(!json) {
451                 osrfLogWarning( OSRF_LOG_MARK,
452                         "osrf_message_deserialize() unable to parse data: \n%s\n", string);
453                 return 0;
454         }
455
456         // Traverse the JSON_ARRAY, turning each element into an osrfMessage
457         int x;
458         for( x = 0; x < json->size && x < count; x++ ) {
459
460                 const jsonObject* message = jsonObjectGetIndex(json, x);
461
462                 if(message && message->type != JSON_NULL &&
463                         message->classname && !strcmp(message->classname, "osrfMessage")) {
464
465                         osrfMessage* new_msg = safe_malloc(sizeof(osrfMessage));
466                         new_msg->m_type = 0;
467                         new_msg->thread_trace = 0;
468                         new_msg->protocol = 0;
469                         new_msg->status_name = NULL;
470                         new_msg->status_text = NULL;
471                         new_msg->status_code = 0;
472                         new_msg->is_exception = 0;
473                         new_msg->_result_content = NULL;
474                         new_msg->result_string = NULL;
475                         new_msg->method_name = NULL;
476                         new_msg->_params = NULL;
477                         new_msg->next = NULL;
478                         new_msg->sender_locale = NULL;
479                         new_msg->sender_tz_offset = 0;
480
481                         // Get the message type.  If not specified, default to CONNECT.
482                         const jsonObject* tmp = jsonObjectGetKeyConst(message, "type");
483
484                         const char* t;
485                         if( ( t = jsonObjectGetString(tmp)) ) {
486
487                                 if(!strcmp(t, "CONNECT"))           new_msg->m_type = CONNECT;
488                                 else if(!strcmp(t, "DISCONNECT"))   new_msg->m_type = DISCONNECT;
489                                 else if(!strcmp(t, "STATUS"))       new_msg->m_type = STATUS;
490                                 else if(!strcmp(t, "REQUEST"))      new_msg->m_type = REQUEST;
491                                 else if(!strcmp(t, "RESULT"))       new_msg->m_type = RESULT;
492                         }
493
494                         // Get the thread trace, defaulting to zero.
495                         tmp = jsonObjectGetKeyConst(message, "threadTrace");
496                         if(tmp) {
497                                 const char* tt = jsonObjectGetString(tmp);
498                                 if(tt) {
499                                         new_msg->thread_trace = atoi(tt);
500                                 }
501                         }
502
503                         // Get the sender's locale, or leave it NULL if not specified.
504                         if (current_locale)
505                                 free( current_locale );
506
507                         tmp = jsonObjectGetKeyConst(message, "locale");
508
509                         if(tmp && (new_msg->sender_locale = jsonObjectToSimpleString(tmp))) {
510                                 current_locale = strdup( new_msg->sender_locale );
511                         } else {
512                                 current_locale = NULL;
513                         }
514
515                         // Get the protocol, defaulting to zero.
516                         tmp = jsonObjectGetKeyConst(message, "protocol");
517
518                         if(tmp) {
519                                 const char* proto = jsonObjectGetString(tmp);
520                                 if(proto) {
521                                         new_msg->protocol = atoi(proto);
522                                 }
523                         }
524
525                         tmp = jsonObjectGetKeyConst(message, "payload");
526                         if(tmp) {
527                                 // Get method name and parameters for a REQUEST
528                                 const jsonObject* tmp0 = jsonObjectGetKeyConst(tmp,"method");
529                                 const char* tmp_str = jsonObjectGetString(tmp0);
530                                 if(tmp_str)
531                                         new_msg->method_name = strdup(tmp_str);
532
533                                 tmp0 = jsonObjectGetKeyConst(tmp,"params");
534                                 if(tmp0) {
535                                         // Note that we use jsonObjectDecodeClass() instead of
536                                         // jsonObjectClone().  The classnames are already decoded,
537                                         // but jsonObjectDecodeClass removes the decoded classnames.
538                                         new_msg->_params = jsonObjectDecodeClass( tmp0 );
539                                         if(new_msg->_params && new_msg->_params->type == JSON_NULL)
540                                                 new_msg->_params->type = JSON_ARRAY;
541                                 }
542
543                                 // Get status fields for a RESULT or STATUS
544                                 if(tmp->classname)
545                                         new_msg->status_name = strdup(tmp->classname);
546
547                                 tmp0 = jsonObjectGetKeyConst(tmp,"status");
548                                 tmp_str = jsonObjectGetString(tmp0);
549                                 if(tmp_str)
550                                         new_msg->status_text = strdup(tmp_str);
551
552                                 tmp0 = jsonObjectGetKeyConst(tmp,"statusCode");
553                                 if(tmp0) {
554                                         tmp_str = jsonObjectGetString(tmp0);
555                                         if(tmp_str)
556                                                 new_msg->status_code = atoi(tmp_str);
557                                         if(tmp0->type == JSON_NUMBER)
558                                                 new_msg->status_code = (int) jsonObjectGetNumber(tmp0);
559                                 }
560
561                                 // Get the content for a RESULT
562                                 tmp0 = jsonObjectGetKeyConst(tmp,"content");
563                                 if(tmp0) {
564                                         // Note that we use jsonObjectDecodeClass() instead of
565                                         // jsonObjectClone().  The classnames are already decoded,
566                                         // but jsonObjectDecodeClass removes the decoded classnames.
567                                         new_msg->_result_content = jsonObjectDecodeClass( tmp0 );
568                                 }
569
570                         }
571                         msgs[numparsed++] = new_msg;
572                 }
573         }
574
575         jsonObjectFree(json);
576         return numparsed;
577 }
578
579
580
581 /**
582         @brief Return a pointer to the result content of an osrfMessage.
583         @param msg Pointer to the osrfMessage whose result content is to be returned.
584         @return Pointer to the result content (or NULL if there is no such content, or if @a msg is NULL).
585
586         The returned pointer points into the innards of the osrfMessage.  The calling code should @em not call
587         jsonObjectFree() on it, because the osrfMessage still owns it.
588 */
589 jsonObject* osrfMessageGetResult( osrfMessage* msg ) {
590         if(msg) return msg->_result_content;
591         return NULL;
592 }
593