LP#1485371: Use client-supplied TZ
[OpenSRF.git] / src / libopensrf / osrf_message.c
1 /**
2         @file osrf_message.c
3         @brief Implementation of osrfMessage.
4 */
5
6 /* libxml stuff for the config reader */
7 #include <libxml/xmlmemory.h>
8 #include <libxml/parser.h>
9 #include <libxml/xpath.h>
10 #include <libxml/xpathInternals.h>
11 #include <libxml/tree.h>
12
13 #include <opensrf/osrf_message.h>
14 #include "opensrf/osrf_stack.h"
15
16 static osrfMessage* deserialize_one_message( const jsonObject* message );
17
18 static char default_locale[17] = "en-US\0\0\0\0\0\0\0\0\0\0\0\0";
19 static char* current_locale = NULL;
20
21 /**
22         @brief Allocate and initialize an osrfMessage.
23         @param type One of CONNECT, REQUEST, RESULT, STATUS, or DISCONNECT.
24         @param thread_trace Thread trace.
25         @param protocol Protocol.
26         @return Pointer to the newly allocated osrfMessage.
27
28         The calling code is responsible for freeing the osrfMessage by calling osrfMessageFree().
29 */
30 osrfMessage* osrf_message_init( enum M_TYPE type, int thread_trace, int protocol ) {
31
32         osrfMessage* msg            = (osrfMessage*) safe_malloc(sizeof(osrfMessage));
33         msg->m_type                 = type;
34         msg->thread_trace           = thread_trace;
35         msg->protocol               = protocol;
36         msg->status_name            = NULL;
37         msg->status_text            = NULL;
38         msg->status_code            = 0;
39         msg->next                   = NULL;
40         msg->is_exception           = 0;
41         msg->_params                = NULL;
42         msg->_result_content        = NULL;
43         msg->method_name            = NULL;
44         msg->sender_locale          = NULL;
45         msg->sender_tz              = NULL;
46         msg->sender_ingress         = NULL;
47
48         return msg;
49 }
50
51
52 /**
53         @brief Return the previous locale.
54         @return A pointer to the locale specified by the last message to have been deserialized,
55                 or NULL.
56
57         A JSON message may specify a locale string, which is saved as the current locale.  If
58         the message does not specify a locale string, then the current locale becomes NULL.
59
60         This function returns a pointer to an internal buffer.  Since both the address and the
61         contents of this buffer may change from one call to the next, the calling code should
62         either use the result immediately or make a copy of the string for later use.
63 */
64 const char* osrf_message_get_last_locale() {
65         return current_locale;
66 }
67
68 /**
69         @brief Set the locale for a specified osrfMessage.
70         @param msg Pointer to the osrfMessage.
71         @param locale Pointer to the locale string to be installed in the osrfMessage.
72         @return Pointer to the new locale string for the osrfMessage, or NULL if either
73                 parameter is NULL.
74
75         If no locale is specified for an osrfMessage, we use the default locale.
76
77         Used for a REQUEST message.
78 */
79 const char* osrf_message_set_locale( osrfMessage* msg, const char* locale ) {
80         if( msg == NULL || locale == NULL )
81                 return NULL;
82         if( msg->sender_locale )
83                 free( msg->sender_locale );
84         return msg->sender_locale = strdup( locale );
85 }
86
87 /**
88         @brief Set the TZ for a specified osrfMessage.
89         @param msg Pointer to the osrfMessage.
90         @param TZ Pointer to the TZ string to be installed in the osrfMessage.
91         @return Pointer to the new TZ string for the osrfMessage, or NULL if either
92                 parameter is NULL.
93
94         If no TZ is specified for an osrfMessage, we use the system TZ.
95
96         Used for a REQUEST message.
97 */
98 const char* osrf_message_set_tz( osrfMessage* msg, const char* tz ) {
99         if( msg == NULL || tz == NULL )
100                 return NULL;
101         if( msg->sender_tz )
102                 free( msg->sender_tz );
103         return msg->sender_tz = strdup( tz );
104 }
105
106 /**
107         @brief Set the ingress for a specified osrfMessage.
108         @param msg Pointer to the osrfMessage.
109         @param ingress Pointer to the ingress string to be installed in the osrfMessage.
110         @return Pointer to the new ingress string for the osrfMessage, or NULL if either
111                 parameter is NULL.
112
113         If no ingress is specified for an osrfMessage, we use the default ingress.
114
115         Used for a REQUEST message.
116 */
117 const char* osrfMessageSetIngress( osrfMessage* msg, const char* ingress ) {
118         if( msg == NULL || ingress == NULL )
119                 return NULL;
120         if( msg->sender_ingress )
121                 free( msg->sender_ingress );
122         return msg->sender_ingress = strdup( ingress );
123 }
124
125 /**
126         @brief Change the default locale.
127         @param locale The new default locale.
128         @return A pointer to the new default locale if successful, or NULL if not.
129
130         The function returns NULL if the parameter is NULL, or if the proposed new locale is
131         longer than 16 characters.
132
133         At this writing, nothing calls this function.
134 */
135 const char* osrf_message_set_default_locale( const char* locale ) {
136         if( locale == NULL ) return NULL;
137         if( strlen(locale) > sizeof(default_locale) - 1 ) return NULL;
138
139         strcpy( default_locale, locale );
140         return default_locale;
141 }
142
143 /**
144         @brief Populate the method_name member of an osrfMessage.
145         @param msg Pointer to the osrfMessage.
146         @param method_name The method name.
147
148         Used for a REQUEST message to specify what method to invoke.
149 */
150 void osrf_message_set_method( osrfMessage* msg, const char* method_name ) {
151         if( msg == NULL || method_name == NULL )
152                 return;
153         if( msg->method_name )
154                 free( msg->method_name );
155         msg->method_name = strdup( method_name );
156 }
157
158
159 /**
160         @brief Add a copy of a jsonObject to an osrfMessage as a parameter for a method call.
161         @param msg Pointer to the osrfMessage.
162         @param o Pointer to the jsonObject of which a copy is to be stored.
163
164         Make a copy of the input jsonObject, with all classnames encoded with JSON_CLASS_KEY and
165         JSON_DATA_KEY.  Append it to a JSON_ARRAY stored at msg->_params.
166
167         If there is nothing at msg->_params, create a new JSON_ARRAY for it and add the new object
168         as the first element.
169
170         If the jsonObject is raw (i.e. the class information has not been decoded into classnames),
171         decode it.  If the class information has already been decoded, discard it.
172
173         See also osrf_message_add_param().
174
175         At this writing, nothing calls this function.
176 */
177 void osrf_message_add_object_param( osrfMessage* msg, const jsonObject* o ) {
178         if(!msg|| !o) return;
179         if(!msg->_params)
180                 msg->_params = jsonNewObjectType( JSON_ARRAY );
181         jsonObjectPush(msg->_params, jsonObjectDecodeClass( o ));
182 }
183
184 /**
185         @brief Populate the params member of an osrfMessage.
186         @param msg Pointer to the osrfMessage.
187         @param o Pointer to a jsonObject representing the parameter(s) to a method.
188
189         Make a copy of a jsonObject and install it as the parameter list for a method call.
190
191         If the osrfMessage already has any parameters, discard them.
192
193         The @a o parameter should point to a jsonObject of type JSON_ARRAY, with each element
194         of the array being a parameter.  If @a o points to any other type of jsonObject, create
195         a JSON_ARRAY as a wrapper for it, and install a copy of @a o as its only element.
196
197         Used for a REQUEST message, to pass parameters to a method.  The alternative is to call
198         osrf_message_add_param() or osrf_message_add_object_param() repeatedly as needed to add
199         one parameter at a time.
200 */
201 void osrf_message_set_params( osrfMessage* msg, const jsonObject* o ) {
202         if(!msg || !o) return;
203
204         if(msg->_params)
205                 jsonObjectFree(msg->_params);
206
207         if(o->type == JSON_ARRAY) {
208                 msg->_params = jsonObjectClone(o);
209         } else {
210                 osrfLogDebug( OSRF_LOG_MARK, "passing non-array to osrf_message_set_params(), fixing...");
211                 jsonObject* clone = jsonObjectClone(o);
212                 msg->_params = jsonNewObjectType( JSON_ARRAY );
213                 jsonObjectPush(msg->_params, clone);
214                 return;
215         }
216 }
217
218
219 /**
220         @brief Add a JSON string to an osrfMessage as a parameter for a method call.
221         @param msg Pointer to the osrfMessage.
222         @param param_string A JSON string encoding the parameter to be added.
223
224         Translate the JSON string into a jsonObject, and append it to the parameter list.
225         If the parameter list doesn't already exist, create an empty one and add the new
226         parameter to it.
227
228         Decode any class information in the raw JSON into classnames.
229
230         If the JSON string is not valid JSON, append a new jsonObject of type JSON_NULL.
231
232         Used for a REQUEST message, to pass a parameter to a method,  The alternative is to
233         call osrf_message_set_params() to provide all the parameters at once.  See also
234         osrf_message_add_object_param().
235 */
236 void osrf_message_add_param( osrfMessage* msg, const char* param_string ) {
237         if(msg == NULL || param_string == NULL) return;
238         if(!msg->_params) msg->_params = jsonNewObjectType( JSON_ARRAY );
239         jsonObjectPush(msg->_params, jsonParse(param_string));
240 }
241
242
243 /**
244         @brief Set the status_name, status_text, and status_code members of an osrfMessage.
245         @param msg Pointer to the osrfMessage to be populated.
246         @param status_name Status name (may be NULL).
247         @param status_text Status text (may be NULL).
248         @param status_code Status code.
249
250         If the @a status_name or @a status_text parameter is NULL, the corresponding member
251         is left unchanged.
252
253         Used for a RESULT or STATUS message.
254 */
255 void osrf_message_set_status_info( osrfMessage* msg,
256                 const char* status_name, const char* status_text, int status_code ) {
257         if(!msg) return;
258
259         if( status_name != NULL ) {
260                 if( msg->status_name )
261                         free( msg->status_name );
262                 msg->status_name = strdup( status_name );
263         }
264
265         if( status_text != NULL ) {
266                 if( msg->status_text )
267                         free( msg->status_text );
268                 msg->status_text = strdup( status_text );
269         }
270
271         msg->status_code = status_code;
272 }
273
274
275 /**
276         @brief Populate the _result_content membersof an osrfMessage from a JSON string.
277         @param msg Pointer to the osrfMessage to be populated.
278         @param json_string A JSON string encoding a result.
279
280         Used for a RESULT message to return the results of a remote procedure call.
281 */
282 void osrf_message_set_result_content( osrfMessage* msg, const char* json_string ) {
283         if( msg == NULL || json_string == NULL) return;
284         if( msg->_result_content )
285                 jsonObjectFree( msg->_result_content );
286
287         msg->_result_content = jsonParse(json_string);
288 }
289
290
291 /**
292         @brief Populate the _result_content membersof an osrfMessage from a JSON object.
293         @param msg Pointer to the osrfMessage to be populated.
294         @param obj Pointer to a jsonObject encoding a result.
295
296         Used for a RESULT message to return the results of a remote procedure call.
297 */
298 void osrf_message_set_result( osrfMessage* msg, const jsonObject* obj ) {
299         if( msg == NULL || obj == NULL) return;
300         if( msg->_result_content )
301                 jsonObjectFree( msg->_result_content );
302
303         msg->_result_content = jsonObjectDecodeClass( obj );
304 }
305
306
307 /**
308         @brief Free an osrfMessage and everything it owns.
309         @param msg Pointer to the osrfMessage to be freed.
310 */
311 void osrfMessageFree( osrfMessage* msg ) {
312         if( msg == NULL )
313                 return;
314
315         if( msg->status_name != NULL )
316                 free(msg->status_name);
317
318         if( msg->status_text != NULL )
319                 free(msg->status_text);
320
321         if( msg->_result_content != NULL )
322                 jsonObjectFree( msg->_result_content );
323
324         if( msg->method_name != NULL )
325                 free(msg->method_name);
326
327         if( msg->sender_locale != NULL )
328                 free(msg->sender_locale);
329
330         if( msg->sender_tz != NULL )
331                 free(msg->sender_tz);
332
333         if( msg->sender_ingress != NULL )
334                 free(msg->sender_ingress);
335
336         if( msg->_params != NULL )
337                 jsonObjectFree(msg->_params);
338
339         free(msg);
340 }
341
342
343 /**
344         @brief Turn a collection of osrfMessages into one big JSON string.
345         @param msgs Pointer to an array of osrfMessages.
346         @param count Maximum number of messages to serialize.
347         @return Pointer to the JSON string.
348
349         Traverse the array, adding each osrfMessage in turn to a JSON_ARRAY.  Stop when you have added
350         the maximum number of messages, or when you encounter a NULL pointer in the array.  Then
351         translate the JSON_ARRAY into a JSON string.
352
353         The calling code is responsible for freeing the returned string.
354 */
355 char* osrfMessageSerializeBatch( osrfMessage* msgs [], int count ) {
356         if( !msgs ) return NULL;
357
358         jsonObject* wrapper = jsonNewObjectType(JSON_ARRAY);
359
360         int i = 0;
361         while( (i < count) && msgs[i] ) {
362                 jsonObjectPush(wrapper, osrfMessageToJSON( msgs[i] ));
363                 ++i;
364         }
365
366         char* j = jsonObjectToJSON(wrapper);
367         jsonObjectFree(wrapper);
368
369         return j;
370 }
371
372
373 /**
374         @brief Turn a single osrfMessage into a JSON string.
375         @param msg Pointer to the osrfMessage to be serialized.
376         @return Pointer to the resulting JSON string.
377
378         Translate the osrfMessage into JSON, wrapped in a JSON array.
379
380         This function is equivalent to osrfMessageSerializeBatch() for an array of one pointer.
381
382         The calling code is responsible for freeing the returned string.
383 */
384 char* osrf_message_serialize(const osrfMessage* msg) {
385
386         if( msg == NULL ) return NULL;
387         char* j = NULL;
388
389         jsonObject* json = osrfMessageToJSON( msg );
390
391         if(json) {
392                 jsonObject* wrapper = jsonNewObjectType(JSON_ARRAY);
393                 jsonObjectPush(wrapper, json);
394                 j = jsonObjectToJSON(wrapper);
395                 jsonObjectFree(wrapper);
396         }
397
398         return j;
399 }
400
401
402 /**
403         @brief Translate an osrfMessage into a jsonObject.
404         @param msg Pointer to the osrfMessage to be translated.
405         @return Pointer to a newly created jsonObject.
406
407         The resulting jsonObject is a JSON_HASH with a classname of "osrfMessage", and the following keys:
408         - "threadTrace"
409         - "locale"
410         - "tz"
411         - "ingress"
412         - "type"
413         - "payload" (only for STATUS, REQUEST, and RESULT messages)
414
415         The data for "payload" is also a JSON_HASH, whose structure depends on the message type:
416
417         For a STATUS message, the payload's classname is msg->status_name.  The keys are "status"
418         (carrying msg->status_text) and "statusCode" (carrying the status code as a string).
419
420         For a REQUEST message, the payload's classname is "osrfMethod".  The keys are "method"
421         (carrying msg->method_name) and "params" (carrying a jsonObject to pass any parameters
422         to the method call).
423
424         For a RESULT message, the payload's classname is "osrfResult".  The keys are "status"
425         (carrying msg->status_text), "statusCode" (carrying the status code as a string), and
426         "content" (carrying a jsonObject to return any results from the method call).
427
428         The calling code is responsible for freeing the returned jsonObject.
429 */
430 jsonObject* osrfMessageToJSON( const osrfMessage* msg ) {
431
432         jsonObject* json = jsonNewObjectType(JSON_HASH);
433         jsonObjectSetClass(json, "osrfMessage");
434         jsonObject* payload;
435         char sc[64];
436         osrf_clearbuf(sc, sizeof(sc));
437
438         INT_TO_STRING(msg->thread_trace);
439         jsonObjectSetKey(json, "threadTrace", jsonNewObject(INTSTR));
440
441         if (msg->sender_locale != NULL) {
442                 jsonObjectSetKey(json, "locale", jsonNewObject(msg->sender_locale));
443         } else if (current_locale != NULL) {
444                 jsonObjectSetKey(json, "locale", jsonNewObject(current_locale));
445         } else {
446                 jsonObjectSetKey(json, "locale", jsonNewObject(default_locale));
447         }
448
449         if (msg->sender_tz != NULL) {
450                 jsonObjectSetKey(json, "tz", jsonNewObject(msg->sender_tz));
451         }
452
453         if (msg->sender_ingress != NULL) 
454                 jsonObjectSetKey(json, "ingress", jsonNewObject(msg->sender_ingress));
455
456         if (msg->protocol > 0) 
457                 jsonObjectSetKey(json, "api_level", jsonNewNumberObject(msg->protocol));
458
459         switch(msg->m_type) {
460
461                 case CONNECT:
462                         jsonObjectSetKey(json, "type", jsonNewObject("CONNECT"));
463                         break;
464
465                 case DISCONNECT:
466                         jsonObjectSetKey(json, "type", jsonNewObject("DISCONNECT"));
467                         break;
468
469                 case STATUS:
470                         jsonObjectSetKey(json, "type", jsonNewObject("STATUS"));
471                         payload = jsonNewObject(NULL);
472                         jsonObjectSetClass(payload, msg->status_name);
473                         jsonObjectSetKey(payload, "status", jsonNewObject(msg->status_text));
474                         snprintf(sc, sizeof(sc), "%d", msg->status_code);
475                         jsonObjectSetKey(payload, "statusCode", jsonNewObject(sc));
476                         jsonObjectSetKey(json, "payload", payload);
477                         break;
478
479                 case REQUEST:
480                         jsonObjectSetKey(json, "type", jsonNewObject("REQUEST"));
481                         payload = jsonNewObject(NULL);
482                         jsonObjectSetClass(payload, "osrfMethod");
483                         jsonObjectSetKey(payload, "method", jsonNewObject(msg->method_name));
484                         jsonObjectSetKey( payload, "params", jsonObjectDecodeClass( msg->_params ) );
485                         jsonObjectSetKey(json, "payload", payload);
486
487                         break;
488
489                 case RESULT:
490                         jsonObjectSetKey(json, "type", jsonNewObject("RESULT"));
491                         payload = jsonNewObject(NULL);
492                         jsonObjectSetClass(payload,"osrfResult");
493                         jsonObjectSetKey(payload, "status", jsonNewObject(msg->status_text));
494                         snprintf(sc, sizeof(sc), "%d", msg->status_code);
495                         jsonObjectSetKey(payload, "statusCode", jsonNewObject(sc));
496                         jsonObjectSetKey(payload, "content", jsonObjectDecodeClass( msg->_result_content ));
497                         jsonObjectSetKey(json, "payload", payload);
498                         break;
499         }
500
501         return json;
502 }
503
504 /**
505         @brief Translate a JSON array into an osrfList of osrfMessages.
506         @param string The JSON string to be translated.
507         @param list Pointer to an osrfList of osrfMessages (may be NULL)
508         @return Pointer to an osrfList containing pointers to osrfMessages.
509
510         The JSON string is expected to be a JSON array, with each element encoding an osrfMessage.
511
512         Translate each element of the JSON array into an osrfMessage, and store a pointer to the
513         osrfMessage in an osrfList.
514
515         If the @a list parameter is NULL, create a new osrfList (with osrfMessageFree() as the
516         callback function for freeing items), populate it, and return a pointer to it.  Otherwise
517         clear the osrfList provided and reuse it.
518
519         When calling osrfMessageDeserialize repeatedly, a reasonable strategy is to pass a NULL
520         for the @a list parameter on the first call, and pass the value returned from the first
521         call on subsequent calls.
522
523         The calling code is responsible for eventually freeing the returned osrfList by calling
524         osrfListFree().
525  */
526 osrfList* osrfMessageDeserialize( const char* string, osrfList* list ) {
527
528         if( list )
529                 osrfListClear( list );
530
531         if( ! string  || ! *string ) {
532                 if( ! list ) {
533                         list = osrfNewList( 1 );
534                         list->freeItem = (void(*)(void*)) osrfMessageFree;
535                 }
536                 return list;                   // No string?  Return empty list.
537         }
538         
539         // Parse the JSON
540         jsonObject* json = jsonParse(string);
541         if(!json) {
542                 osrfLogWarning( OSRF_LOG_MARK,
543                                 "osrfMessageDeserialize() unable to parse data: \n%s\n", string);
544                 if( ! list ) {
545                         list = osrfNewList( 1 );
546                         list->freeItem = (void(*)(void*)) osrfMessageFree;
547                 }
548                 return list;                   // Bad JSON?  Return empty list.
549         }
550
551         const unsigned int count = (int) json->size;
552         if( ! list ) {
553                 // Create a right-sized osrfList
554                 list = osrfNewList( count );
555                 list->freeItem = (void(*)(void*)) osrfMessageFree;
556         }
557
558         // Traverse the JSON_ARRAY, turning each element into an osrfMessage
559         int i;
560         for( i = 0; i < count; ++i ) {
561
562                 const jsonObject* message = jsonObjectGetIndex( json, i );
563                 if( message && message->type != JSON_NULL &&
564                                   message->classname && !strcmp(message->classname, "osrfMessage" )) {
565                         osrfListPush( list, deserialize_one_message( message ) );
566                 }
567         }
568
569         jsonObjectFree( json );
570         return list;
571 }
572
573 /**
574         @brief Translate a JSON array into an array of osrfMessages.
575         @param string The JSON string to be translated.
576         @param msgs Pointer to an array of pointers to osrfMessage, to receive the results.
577         @param count How many slots are available in the @a msgs array.
578         @return The number of osrfMessages created.
579
580         The JSON string is expected to be a JSON array, with each element encoding an osrfMessage.
581
582         If there are too many messages in the JSON array to fit into the pointer array, we
583         silently ignore the excess.
584 */
585 int osrf_message_deserialize(const char* string, osrfMessage* msgs[], int count) {
586
587         if(!string || !msgs || count <= 0) return 0;
588         int numparsed = 0;
589
590         // Parse the JSON
591         jsonObject* json = jsonParse(string);
592
593         if(!json) {
594                 osrfLogWarning( OSRF_LOG_MARK,
595                         "osrf_message_deserialize() unable to parse data: \n%s\n", string);
596                 return 0;
597         }
598
599         // Traverse the JSON_ARRAY, turning each element into an osrfMessage
600         int x;
601         for( x = 0; x < json->size && x < count; x++ ) {
602
603                 const jsonObject* message = jsonObjectGetIndex( json, x );
604
605                 if( message && message->type != JSON_NULL &&
606                         message->classname && !strcmp(message->classname, "osrfMessage" )) {
607                         msgs[numparsed++] = deserialize_one_message( message );
608                 }
609         }
610
611         jsonObjectFree( json );
612         return numparsed;
613 }
614
615
616 /**
617         @brief Translate a jsonObject into a single osrfMessage.
618         @param obj Pointer to the jsonObject to be translated.
619         @return Pointer to a newly created osrfMessage.
620
621         It is assumed that @a obj is non-NULL and points to a valid representation of a message.
622         For a description of the expected structure of this representations, see osrfMessageToJSON().
623
624         The calling code is responsible for freeing the osrfMessage by calling osrfMessageFree().
625 */
626 static osrfMessage* deserialize_one_message( const jsonObject* obj ) {
627
628         // Get the message type.  If it isn't present, default to CONNECT.
629         const jsonObject* tmp = jsonObjectGetKeyConst( obj, "type" );
630
631         enum M_TYPE type = CONNECT;
632         const char* t = jsonObjectGetString( tmp );
633         if( t ) {
634
635                 if(      !strcmp( t, "CONNECT"    ))   type = CONNECT;
636                 else if( !strcmp( t, "DISCONNECT" ))   type = DISCONNECT;
637                 else if( !strcmp( t, "STATUS"     ))   type = STATUS;
638                 else if( !strcmp( t, "REQUEST"    ))   type = REQUEST;
639                 else if( !strcmp( t, "RESULT"     ))   type = RESULT;
640         }
641
642         // Get the thread trace, defaulting to zero.
643         int trace = 0;
644         tmp = jsonObjectGetKeyConst( obj, "threadTrace" );
645         if( tmp ) {
646                 const char* tt = jsonObjectGetString( tmp );
647                 if( tt ) {
648                         trace = atoi( tt );
649                 }
650         }
651
652         // Get the protocol, defaulting to zero.
653         int protocol = 0;
654         tmp = jsonObjectGetKeyConst( obj, "api_level" );
655         if(tmp) {
656                 const char* proto = jsonObjectGetString(tmp);
657                 if( proto ) {
658                         protocol = atoi( proto );
659                 }
660         }
661
662         // Now that we have the essentials, create an osrfMessage
663         osrfMessage* msg = osrf_message_init( type, trace, protocol );
664
665         // Update current_locale with the locale of the message
666         // (or set it to NULL if not specified)
667         tmp = jsonObjectGetKeyConst( obj, "locale" );
668         if(tmp && ( msg->sender_locale = jsonObjectToSimpleString(tmp))) {
669                 if ( current_locale ) {
670                         if( strcmp( current_locale, msg->sender_locale ) ) {
671                                 free( current_locale );
672                                 current_locale = strdup( msg->sender_locale );
673                         } // else they're the same already, so don't replace one with the other
674                 } else
675                         current_locale = strdup( msg->sender_locale );
676         } else {
677                 if ( current_locale ) {
678                         free( current_locale );
679                         current_locale = NULL;
680                 }
681         }
682
683         tmp = jsonObjectGetKeyConst(obj, "ingress");
684         if (tmp) {
685                 osrfMessageSetIngress(msg, jsonObjectGetString(tmp));
686         }
687
688         tmp = jsonObjectGetKeyConst(obj, "tz");
689         if (tmp) {
690                 osrf_message_set_tz(msg, jsonObjectGetString(tmp));
691         }
692
693         tmp = jsonObjectGetKeyConst( obj, "payload" );
694         if(tmp) {
695                 // Get method name and parameters for a REQUEST
696                 const jsonObject* tmp0 = jsonObjectGetKeyConst(tmp,"method");
697                 const char* tmp_str = jsonObjectGetString(tmp0);
698                 if(tmp_str)
699                         msg->method_name = strdup(tmp_str);
700
701                 tmp0 = jsonObjectGetKeyConst(tmp,"params");
702                 if(tmp0) {
703                         // Note that we use jsonObjectDecodeClass() instead of
704                         // jsonObjectClone().  The classnames are already decoded,
705                         // but jsonObjectDecodeClass removes the decoded classnames.
706                         msg->_params = jsonObjectDecodeClass( tmp0 );
707                         if(msg->_params && msg->_params->type == JSON_NULL)
708                                 msg->_params->type = JSON_ARRAY;
709                 }
710
711                 // Get status fields for a RESULT or STATUS
712                 if(tmp->classname)
713                         msg->status_name = strdup(tmp->classname);
714
715                 tmp0 = jsonObjectGetKeyConst(tmp,"status");
716                 tmp_str = jsonObjectGetString(tmp0);
717                 if(tmp_str)
718                         msg->status_text = strdup(tmp_str);
719
720                 tmp0 = jsonObjectGetKeyConst(tmp,"statusCode");
721                 if(tmp0) {
722                         tmp_str = jsonObjectGetString(tmp0);
723                         if(tmp_str)
724                                 msg->status_code = atoi(tmp_str);
725                         if(tmp0->type == JSON_NUMBER)
726                                 msg->status_code = (int) jsonObjectGetNumber(tmp0);
727                 }
728
729                 // Get the content for a RESULT
730                 tmp0 = jsonObjectGetKeyConst(tmp,"content");
731                 if(tmp0) {
732                         // Note that we use jsonObjectDecodeClass() instead of
733                         // jsonObjectClone().  The classnames are already decoded,
734                         // but jsonObjectDecodeClass removes the decoded classnames.
735                         msg->_result_content = jsonObjectDecodeClass( tmp0 );
736                 }
737
738         }
739
740         return msg;
741 }
742
743
744 /**
745         @brief Return a pointer to the result content of an osrfMessage.
746         @param msg Pointer to the osrfMessage whose result content is to be returned.
747         @return Pointer to the result content (or NULL if there is no such content, or if @a msg is
748         NULL).
749
750         The returned pointer points into the innards of the osrfMessage.  The calling code should
751         @em not call jsonObjectFree() on it, because the osrfMessage still owns it.
752 */
753 const jsonObject* osrfMessageGetResult( osrfMessage* msg ) {
754         if(msg) return msg->_result_content;
755         return NULL;
756 }