release/src/router/libjson-c/json_object.h

   1 /*
   2  * $Id: json_object.h,v 1.12 2006/01/30 23:07:57 mclark Exp $
   3  *
   4  * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
   5  * Michael Clark <michael@metaparadigm.com>
   6  * Copyright (c) 2009 Hewlett-Packard Development Company, L.P.
   7  *
   8  * This library is free software; you can redistribute it and/or modify
   9  * it under the terms of the MIT license. See COPYING for details.
  10  *
  11  */
  12
  13 #ifndef _json_object_h_
  14 #define _json_object_h_
  15
  16 #ifdef __GNUC__
  17 #define THIS_FUNCTION_IS_DEPRECATED(func) func __attribute__ ((deprecated))
  18 #elif defined(_MSC_VER)
  19 #define THIS_FUNCTION_IS_DEPRECATED(func) __declspec(deprecated) func
  20 #else
  21 #define THIS_FUNCTION_IS_DEPRECATED(func) func
  22 #endif
  23
  24 #include "json_inttypes.h"
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #define JSON_OBJECT_DEF_HASH_ENTRIES 16
  31
  32 /**
  33  * A flag for the json_object_to_json_string_ext() and
  34  * json_object_to_file_ext() functions which causes the output
  35  * to have no extra whitespace or formatting applied.
  36  */
  37 #define JSON_C_TO_STRING_PLAIN      0
  38 /**
  39  * A flag for the json_object_to_json_string_ext() and
  40  * json_object_to_file_ext() functions which causes the output to have
  41  * minimal whitespace inserted to make things slightly more readable.
  42  */
  43 #define JSON_C_TO_STRING_SPACED     (1<<0)
  44 /**
  45  * A flag for the json_object_to_json_string_ext() and
  46  * json_object_to_file_ext() functions which causes
  47  * the output to be formatted.
  48  *
  49  * See the "Two Space Tab" option at http://jsonformatter.curiousconcept.com/
  50  * for an example of the format.
  51  */
  52 #define JSON_C_TO_STRING_PRETTY     (1<<1)
  53 /**
  54  * A flag to drop trailing zero for float values
  55  */
  56 #define JSON_C_TO_STRING_NOZERO     (1<<2)
  57
  58 #undef FALSE
  59 #define FALSE ((json_bool)0)
  60
  61 #undef TRUE
  62 #define TRUE ((json_bool)1)
  63
  64 extern const char *json_number_chars;
  65 extern const char *json_hex_chars;
  66
  67 /* CAW: added for ANSI C iteration correctness */
  68 struct json_object_iter
  69 {
  70         char *key;
  71         struct json_object *val;
  72         struct lh_entry *entry;
  73 };
  74
  75 /* forward structure definitions */
  76
  77 typedef int json_bool;
  78 typedef struct printbuf printbuf;
  79 typedef struct lh_table lh_table;
  80 typedef struct array_list array_list;
  81 typedef struct json_object json_object;
  82 typedef struct json_object_iter json_object_iter;
  83 typedef struct json_tokener json_tokener;
  84
  85 /**
  86  * Type of custom user delete functions.  See json_object_set_serializer.
  87  */
  88 typedef void (json_object_delete_fn)(struct json_object *jso, void *userdata);
  89
  90 /**
  91  * Type of a custom serialization function.  See json_object_set_serializer.
  92  */
  93 typedef int (json_object_to_json_string_fn)(struct json_object *jso,
  94                                                 struct printbuf *pb,
  95                                                 int level,
  96                                                 int flags);
  97
  98 /* supported object types */
  99
 100 typedef enum json_type {
 101   /* If you change this, be sure to update json_type_to_name() too */
 102   json_type_null,
 103   json_type_boolean,
 104   json_type_double,
 105   json_type_int,
 106   json_type_object,
 107   json_type_array,
 108   json_type_string,
 109 } json_type;
 110
 111 /* reference counting functions */
 112
 113 /**
 114  * Increment the reference count of json_object, thereby grabbing shared
 115  * ownership of obj.
 116  *
 117  * @param obj the json_object instance
 118  */
 119 extern struct json_object* json_object_get(struct json_object *obj);
 120
 121 /**
 122  * Decrement the reference count of json_object and free if it reaches zero.
 123  * You must have ownership of obj prior to doing this or you will cause an
 124  * imbalance in the reference count.
 125  *
 126  * @param obj the json_object instance
 127  * @returns 1 if the object was freed.
 128  */
 129 int json_object_put(struct json_object *obj);
 130
 131 /**
 132  * Check if the json_object is of a given type
 133  * @param obj the json_object instance
 134  * @param type one of:
 135      json_type_null (i.e. obj == NULL),
 136      json_type_boolean,
 137      json_type_double,
 138      json_type_int,
 139      json_type_object,
 140      json_type_array,
 141      json_type_string,
 142  */
 143 extern int json_object_is_type(struct json_object *obj, enum json_type type);
 144
 145 /**
 146  * Get the type of the json_object.  See also json_type_to_name() to turn this
 147  * into a string suitable, for instance, for logging.
 148  *
 149  * @param obj the json_object instance
 150  * @returns type being one of:
 151      json_type_null (i.e. obj == NULL),
 152      json_type_boolean,
 153      json_type_double,
 154      json_type_int,
 155      json_type_object,
 156      json_type_array,
 157      json_type_string,
 158  */
 159 extern enum json_type json_object_get_type(struct json_object *obj);
 160
 161
 162 /** Stringify object to json format.
 163  * Equivalent to json_object_to_json_string_ext(obj, JSON_C_TO_STRING_SPACED)
 164  * @param obj the json_object instance
 165  * @returns a string in JSON format
 166  */
 167 extern const char* json_object_to_json_string(struct json_object *obj);
 168
 169 /** Stringify object to json format
 170  * @param obj the json_object instance
 171  * @param flags formatting options, see JSON_C_TO_STRING_PRETTY and other constants
 172  * @returns a string in JSON format
 173  */
 174 extern const char* json_object_to_json_string_ext(struct json_object *obj, int
 175 flags);
 176
 177 /**
 178  * Set a custom serialization function to be used when this particular object
 179  * is converted to a string by json_object_to_json_string.
 180  *
 181  * If a custom serializer is already set on this object, any existing
 182  * user_delete function is called before the new one is set.
 183  *
 184  * If to_string_func is NULL, the other parameters are ignored
 185  * and the default behaviour is reset.
 186  *
 187  * The userdata parameter is optional and may be passed as NULL.  If provided,
 188  * it is passed to to_string_func as-is.  This parameter may be NULL even
 189  * if user_delete is non-NULL.
 190  *
 191  * The user_delete parameter is optional and may be passed as NULL, even if
 192  * the userdata parameter is non-NULL.  It will be called just before the
 193  * json_object is deleted, after it's reference count goes to zero
 194  * (see json_object_put()).
 195  * If this is not provided, it is up to the caller to free the userdata at
 196  * an appropriate time. (i.e. after the json_object is deleted)
 197  *
 198  * @param jso the object to customize
 199  * @param to_string_func the custom serialization function
 200  * @param userdata an optional opaque cookie
 201  * @param user_delete an optional function from freeing userdata
 202  */
 203 extern void json_object_set_serializer(json_object *jso,
 204         json_object_to_json_string_fn to_string_func,
 205         void *userdata,
 206         json_object_delete_fn *user_delete);
 207
 208 /**
 209  * Simply call free on the userdata pointer.
 210  * Can be used with json_object_set_serializer().
 211  *
 212  * @param jso unused
 213  * @param userdata the pointer that is passed to free().
 214  */
 215 json_object_delete_fn json_object_free_userdata;
 216
 217 /**
 218  * Copy the jso->_userdata string over to pb as-is.
 219  * Can be used with json_object_set_serializer().
 220  *
 221  * @param jso The object whose _userdata is used.
 222  * @param pb The destination buffer.
 223  * @param level Ignored.
 224  * @param flags Ignored.
 225  */
 226 json_object_to_json_string_fn json_object_userdata_to_json_string;
 227
 228
 229 /* object type methods */
 230
 231 /** Create a new empty object with a reference count of 1.  The caller of
 232  * this object initially has sole ownership.  Remember, when using
 233  * json_object_object_add or json_object_array_put_idx, ownership will
 234  * transfer to the object/array.  Call json_object_get if you want to maintain
 235  * shared ownership or also add this object as a child of multiple objects or
 236  * arrays.  Any ownerships you acquired but did not transfer must be released
 237  * through json_object_put.
 238  *
 239  * @returns a json_object of type json_type_object
 240  */
 241 extern struct json_object* json_object_new_object(void);
 242
 243 /** Get the hashtable of a json_object of type json_type_object
 244  * @param obj the json_object instance
 245  * @returns a linkhash
 246  */
 247 extern struct lh_table* json_object_get_object(struct json_object *obj);
 248
 249 /** Get the size of an object in terms of the number of fields it has.
 250  * @param obj the json_object whose length to return
 251  */
 252 extern int json_object_object_length(struct json_object* obj);
 253
 254 /** Add an object field to a json_object of type json_type_object
 255  *
 256  * The reference count will *not* be incremented. This is to make adding
 257  * fields to objects in code more compact. If you want to retain a reference
 258  * to an added object, independent of the lifetime of obj, you must wrap the
 259  * passed object with json_object_get.
 260  *
 261  * Upon calling this, the ownership of val transfers to obj.  Thus you must
 262  * make sure that you do in fact have ownership over this object.  For instance,
 263  * json_object_new_object will give you ownership until you transfer it,
 264  * whereas json_object_object_get does not.
 265  *
 266  * @param obj the json_object instance
 267  * @param key the object field name (a private copy will be duplicated)
 268  * @param val a json_object or NULL member to associate with the given field
 269  */
 270 extern void json_object_object_add(struct json_object* obj, const char *key,
 271                                    struct json_object *val);
 272
 273 /** Get the json_object associate with a given object field
 274  *
 275  * *No* reference counts will be changed.  There is no need to manually adjust
 276  * reference counts through the json_object_put/json_object_get methods unless
 277  * you need to have the child (value) reference maintain a different lifetime
 278  * than the owning parent (obj). Ownership of the returned value is retained
 279  * by obj (do not do json_object_put unless you have done a json_object_get).
 280  * If you delete the value from obj (json_object_object_del) and wish to access
 281  * the returned reference afterwards, make sure you have first gotten shared
 282  * ownership through json_object_get (& don't forget to do a json_object_put
 283  * or transfer ownership to prevent a memory leak).
 284  *
 285  * @param obj the json_object instance
 286  * @param key the object field name
 287  * @returns the json_object associated with the given field name
 288  * @deprecated Please use json_object_object_get_ex
 289  */
 290 THIS_FUNCTION_IS_DEPRECATED(extern struct json_object* json_object_object_get(struct json_object* obj,
 291                                                   const char *key));
 292
 293 /** Get the json_object associated with a given object field.
 294  *
 295  * This returns true if the key is found, false in all other cases (including
 296  * if obj isn't a json_type_object).
 297  *
 298  * *No* reference counts will be changed.  There is no need to manually adjust
 299  * reference counts through the json_object_put/json_object_get methods unless
 300  * you need to have the child (value) reference maintain a different lifetime
 301  * than the owning parent (obj).  Ownership of value is retained by obj.
 302  *
 303  * @param obj the json_object instance
 304  * @param key the object field name
 305  * @param value a pointer where to store a reference to the json_object
 306  *              associated with the given field name.
 307  *
 308  *              It is safe to pass a NULL value.
 309  * @returns whether or not the key exists
 310  */
 311 extern json_bool json_object_object_get_ex(struct json_object* obj,
 312                                                   const char *key,
 313                                                   struct json_object **value);
 314
 315 /** Delete the given json_object field
 316  *
 317  * The reference count will be decremented for the deleted object.  If there
 318  * are no more owners of the value represented by this key, then the value is
 319  * freed.  Otherwise, the reference to the value will remain in memory.
 320  *
 321  * @param obj the json_object instance
 322  * @param key the object field name
 323  */
 324 extern void json_object_object_del(struct json_object* obj, const char *key);
 325
 326 /**
 327  * Iterate through all keys and values of an object.
 328  *
 329  * Adding keys to the object while iterating is NOT allowed.
 330  *
 331  * Deleting an existing key, or replacing an existing key with a
 332  * new value IS allowed.
 333  *
 334  * @param obj the json_object instance
 335  * @param key the local name for the char* key variable defined in the body
 336  * @param val the local name for the json_object* object variable defined in
 337  *            the body
 338  */
 339 #if defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L
 340
 341 # define json_object_object_foreach(obj,key,val) \
 342         char *key; \
 343         struct json_object *val __attribute__((__unused__)); \
 344         for(struct lh_entry *entry ## key = json_object_get_object(obj)->head, *entry_next ## key = NULL; \
 345                 ({ if(entry ## key) { \
 346                         key = (char*)entry ## key->k; \
 347                         val = (struct json_object*)entry ## key->v; \
 348                         entry_next ## key = entry ## key->next; \
 349                 } ; entry ## key; }); \
 350                 entry ## key = entry_next ## key )
 351
 352 #else /* ANSI C or MSC */
 353
 354 # define json_object_object_foreach(obj,key,val) \
 355         char *key;\
 356         struct json_object *val; \
 357         struct lh_entry *entry ## key; \
 358         struct lh_entry *entry_next ## key = NULL; \
 359         for(entry ## key = json_object_get_object(obj)->head; \
 360                 (entry ## key ? ( \
 361                         key = (char*)entry ## key->k, \
 362                         val = (struct json_object*)entry ## key->v, \
 363                         entry_next ## key = entry ## key->next, \
 364                         entry ## key) : 0); \
 365                 entry ## key = entry_next ## key)
 366
 367 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L */
 368
 369 /** Iterate through all keys and values of an object (ANSI C Safe)
 370  * @param obj the json_object instance
 371  * @param iter the object iterator
 372  */
 373 #define json_object_object_foreachC(obj,iter) \
 374  for(iter.entry = json_object_get_object(obj)->head; (iter.entry ? (iter.key = (char*)iter.entry->k, iter.val = (struct json_object*)iter.entry->v, iter.entry) : 0); iter.entry = iter.entry->next)
 375
 376 /* Array type methods */
 377
 378 /** Create a new empty json_object of type json_type_array
 379  * @returns a json_object of type json_type_array
 380  */
 381 extern struct json_object* json_object_new_array(void);
 382
 383 /** Get the arraylist of a json_object of type json_type_array
 384  * @param obj the json_object instance
 385  * @returns an arraylist
 386  */
 387 extern struct array_list* json_object_get_array(struct json_object *obj);
 388
 389 /** Get the length of a json_object of type json_type_array
 390  * @param obj the json_object instance
 391  * @returns an int
 392  */
 393 extern int json_object_array_length(struct json_object *obj);
 394
 395 /** Sorts the elements of jso of type json_type_array
 396 *
 397 * Pointers to the json_object pointers will be passed as the two arguments
 398 * to @sort_fn
 399 *
 400 * @param obj the json_object instance
 401 * @param sort_fn a sorting function
 402 */
 403 extern void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *));
 404
 405 /** Add an element to the end of a json_object of type json_type_array
 406  *
 407  * The reference count will *not* be incremented. This is to make adding
 408  * fields to objects in code more compact. If you want to retain a reference
 409  * to an added object you must wrap the passed object with json_object_get
 410  *
 411  * @param obj the json_object instance
 412  * @param val the json_object to be added
 413  */
 414 extern int json_object_array_add(struct json_object *obj,
 415                                  struct json_object *val);
 416
 417 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
 418  *
 419  * The reference count will *not* be incremented. This is to make adding
 420  * fields to objects in code more compact. If you want to retain a reference
 421  * to an added object you must wrap the passed object with json_object_get
 422  *
 423  * The reference count of a replaced object will be decremented.
 424  *
 425  * The array size will be automatically be expanded to the size of the
 426  * index if the index is larger than the current size.
 427  *
 428  * @param obj the json_object instance
 429  * @param idx the index to insert the element at
 430  * @param val the json_object to be added
 431  */
 432 extern int json_object_array_put_idx(struct json_object *obj, int idx,
 433                                      struct json_object *val);
 434
 435 /** Get the element at specificed index of the array (a json_object of type json_type_array)
 436  * @param obj the json_object instance
 437  * @param idx the index to get the element at
 438  * @returns the json_object at the specified index (or NULL)
 439  */
 440 extern struct json_object* json_object_array_get_idx(struct json_object *obj,
 441                                                      int idx);
 442
 443 /* json_bool type methods */
 444
 445 /** Create a new empty json_object of type json_type_boolean
 446  * @param b a json_bool TRUE or FALSE (0 or 1)
 447  * @returns a json_object of type json_type_boolean
 448  */
 449 extern struct json_object* json_object_new_boolean(json_bool b);
 450
 451 /** Get the json_bool value of a json_object
 452  *
 453  * The type is coerced to a json_bool if the passed object is not a json_bool.
 454  * integer and double objects will return FALSE if there value is zero
 455  * or TRUE otherwise. If the passed object is a string it will return
 456  * TRUE if it has a non zero length. If any other object type is passed
 457  * TRUE will be returned if the object is not NULL.
 458  *
 459  * @param obj the json_object instance
 460  * @returns a json_bool
 461  */
 462 extern json_bool json_object_get_boolean(struct json_object *obj);
 463
 464
 465 /* int type methods */
 466
 467 /** Create a new empty json_object of type json_type_int
 468  * Note that values are stored as 64-bit values internally.
 469  * To ensure the full range is maintained, use json_object_new_int64 instead.
 470  * @param i the integer
 471  * @returns a json_object of type json_type_int
 472  */
 473 extern struct json_object* json_object_new_int(int32_t i);
 474
 475
 476 /** Create a new empty json_object of type json_type_int
 477  * @param i the integer
 478  * @returns a json_object of type json_type_int
 479  */
 480 extern struct json_object* json_object_new_int64(int64_t i);
 481
 482
 483 /** Get the int value of a json_object
 484  *
 485  * The type is coerced to a int if the passed object is not a int.
 486  * double objects will return their integer conversion. Strings will be
 487  * parsed as an integer. If no conversion exists then 0 is returned
 488  * and errno is set to EINVAL. null is equivalent to 0 (no error values set)
 489  *
 490  * Note that integers are stored internally as 64-bit values.
 491  * If the value of too big or too small to fit into 32-bit, INT32_MAX or
 492  * INT32_MIN are returned, respectively.
 493  *
 494  * @param obj the json_object instance
 495  * @returns an int
 496  */
 497 extern int32_t json_object_get_int(struct json_object *obj);
 498
 499 /** Get the int value of a json_object
 500  *
 501  * The type is coerced to a int64 if the passed object is not a int64.
 502  * double objects will return their int64 conversion. Strings will be
 503  * parsed as an int64. If no conversion exists then 0 is returned.
 504  *
 505  * NOTE: Set errno to 0 directly before a call to this function to determine
 506  * whether or not conversion was successful (it does not clear the value for
 507  * you).
 508  *
 509  * @param obj the json_object instance
 510  * @returns an int64
 511  */
 512 extern int64_t json_object_get_int64(struct json_object *obj);
 513
 514
 515 /* double type methods */
 516
 517 /** Create a new empty json_object of type json_type_double
 518  * @param d the double
 519  * @returns a json_object of type json_type_double
 520  */
 521 extern struct json_object* json_object_new_double(double d);
 522
 523 /**
 524  * Create a new json_object of type json_type_double, using
 525  * the exact serialized representation of the value.
 526  *
 527  * This allows for numbers that would otherwise get displayed
 528  * inefficiently (e.g. 12.3 => "12.300000000000001") to be
 529  * serialized with the more convenient form.
 530  *
 531  * Note: this is used by json_tokener_parse_ex() to allow for
 532  *   an exact re-serialization of a parsed object.
 533  *
 534  * An equivalent sequence of calls is:
 535  * @code
 536  *   jso = json_object_new_double(d);
 537  *   json_object_set_serializer(d, json_object_userdata_to_json_string,
 538  *       strdup(ds), json_object_free_userdata)
 539  * @endcode
 540  *
 541  * @param d the numeric value of the double.
 542  * @param ds the string representation of the double.  This will be copied.
 543  */
 544 extern struct json_object* json_object_new_double_s(double d, const char *ds);
 545
 546 /** Get the double floating point value of a json_object
 547  *
 548  * The type is coerced to a double if the passed object is not a double.
 549  * integer objects will return their double conversion. Strings will be
 550  * parsed as a double. If no conversion exists then 0.0 is returned and
 551  * errno is set to EINVAL. null is equivalent to 0 (no error values set)
 552  *
 553  * If the value is too big to fit in a double, then the value is set to
 554  * the closest infinity with errno set to ERANGE. If strings cannot be
 555  * converted to their double value, then EINVAL is set & NaN is returned.
 556  *
 557  * Arrays of length 0 are interpreted as 0 (with no error flags set).
 558  * Arrays of length 1 are effectively cast to the equivalent object and
 559  * converted using the above rules.  All other arrays set the error to
 560  * EINVAL & return NaN.
 561  *
 562  * NOTE: Set errno to 0 directly before a call to this function to
 563  * determine whether or not conversion was successful (it does not clear
 564  * the value for you).
 565  *
 566  * @param obj the json_object instance
 567  * @returns a double floating point number
 568  */
 569 extern double json_object_get_double(struct json_object *obj);
 570
 571
 572 /* string type methods */
 573
 574 /** Create a new empty json_object of type json_type_string
 575  *
 576  * A copy of the string is made and the memory is managed by the json_object
 577  *
 578  * @param s the string
 579  * @returns a json_object of type json_type_string
 580  */
 581 extern struct json_object* json_object_new_string(const char *s);
 582
 583 extern struct json_object* json_object_new_string_len(const char *s, int len);
 584
 585 /** Get the string value of a json_object
 586  *
 587  * If the passed object is not of type json_type_string then the JSON
 588  * representation of the object is returned.
 589  *
 590  * The returned string memory is managed by the json_object and will
 591  * be freed when the reference count of the json_object drops to zero.
 592  *
 593  * @param obj the json_object instance
 594  * @returns a string
 595  */
 596 extern const char* json_object_get_string(struct json_object *obj);
 597
 598 /** Get the string length of a json_object
 599  *
 600  * If the passed object is not of type json_type_string then zero
 601  * will be returned.
 602  *
 603  * @param obj the json_object instance
 604  * @returns int
 605  */
 606 extern int json_object_get_string_len(struct json_object *obj);
 607
 608 #ifdef __cplusplus
 609 }
 610 #endif
 611
 612 #endif