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