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