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 /* supported object types */
  74
  75 typedef enum json_type {
  76   /* If you change this, be sure to update json_type_to_name() too */
  77   json_type_null,
  78   json_type_boolean,
  79   json_type_double,
  80   json_type_int,
  81   json_type_object,
  82   json_type_array,
  83   json_type_string,
  84 } json_type;
  85
  86 /* reference counting functions */
  87
  88 /**
  89  * Increment the reference count of json_object, thereby grabbing shared
  90  * ownership of obj.
  91  *
  92  * @param obj the json_object instance
  93  */
  94 extern struct json_object* json_object_get(struct json_object *obj);
  95
  96 /**
  97  * Decrement the reference count of json_object and free if it reaches zero.
  98  * You must have ownership of obj prior to doing this or you will cause an
  99  * imbalance in the reference count.
 100  *
 101  * @param obj the json_object instance
 102  */
 103 extern void json_object_put(struct json_object *obj);
 104
 105
 106 /**
 107  * Check if the json_object is of a given type
 108  * @param obj the json_object instance
 109  * @param type one of:
 110      json_type_null (i.e. obj == NULL),
 111      json_type_boolean,
 112      json_type_double,
 113      json_type_int,
 114      json_type_object,
 115      json_type_array,
 116      json_type_string,
 117  */
 118 extern int json_object_is_type(struct json_object *obj, enum json_type type);
 119
 120 /**
 121  * Get the type of the json_object.  See also json_type_to_name() to turn this
 122  * into a string suitable, for instance, for logging.
 123  *
 124  * @param obj the json_object instance
 125  * @returns type being one of:
 126      json_type_null (i.e. obj == NULL),
 127      json_type_boolean,
 128      json_type_double,
 129      json_type_int,
 130      json_type_object,
 131      json_type_array,
 132      json_type_string,
 133  */
 134 extern enum json_type json_object_get_type(struct json_object *obj);
 135
 136
 137 /** Stringify object to json format.
 138  * Equivalent to json_object_to_json_string_ext(obj, JSON_C_TO_STRING_SPACED)
 139  * @param obj the json_object instance
 140  * @returns a string in JSON format
 141  */
 142 extern const char* json_object_to_json_string(struct json_object *obj);
 143
 144 /** Stringify object to json format
 145  * @param obj the json_object instance
 146  * @param flags formatting options, see JSON_C_TO_STRING_PRETTY and other constants
 147  * @returns a string in JSON format
 148  */
 149 extern const char* json_object_to_json_string_ext(struct json_object *obj, int
 150 flags);
 151
 152
 153 /* object type methods */
 154
 155 /** Create a new empty object with a reference count of 1.  The caller of
 156  * this object initially has sole ownership.  Remember, when using
 157  * json_object_object_add or json_object_array_put_idx, ownership will
 158  * transfer to the object/array.  Call json_object_get if you want to maintain
 159  * shared ownership or also add this object as a child of multiple objects or
 160  * arrays.  Any ownerships you acquired but did not transfer must be released
 161  * through json_object_put.
 162  *
 163  * @returns a json_object of type json_type_object
 164  */
 165 extern struct json_object* json_object_new_object(void);
 166
 167 /** Get the hashtable of a json_object of type json_type_object
 168  * @param obj the json_object instance
 169  * @returns a linkhash
 170  */
 171 extern struct lh_table* json_object_get_object(struct json_object *obj);
 172
 173 /** Add an object field to a json_object of type json_type_object
 174  *
 175  * The reference count will *not* be incremented. This is to make adding
 176  * fields to objects in code more compact. If you want to retain a reference
 177  * to an added object, independent of the lifetime of obj, you must wrap the
 178  * passed object with json_object_get.
 179  *
 180  * Upon calling this, the ownership of val transfers to obj.  Thus you must
 181  * make sure that you do in fact have ownership over this object.  For instance,
 182  * json_object_new_object will give you ownership until you transfer it,
 183  * whereas json_object_object_get does not.
 184  *
 185  * @param obj the json_object instance
 186  * @param key the object field name (a private copy will be duplicated)
 187  * @param val a json_object or NULL member to associate with the given field
 188  */
 189 extern void json_object_object_add(struct json_object* obj, const char *key,
 190                                    struct json_object *val);
 191
 192 /** Get the json_object associate with a given object field
 193  *
 194  * *No* reference counts will be changed.  There is no need to manually adjust
 195  * reference counts through the json_object_put/json_object_get methods unless
 196  * you need to have the child (value) reference maintain a different lifetime
 197  * than the owning parent (obj). Ownership of the returned value is retained
 198  * by obj (do not do json_object_put unless you have done a json_object_get).
 199  * If you delete the value from obj (json_object_object_del) and wish to access
 200  * the returned reference afterwards, make sure you have first gotten shared
 201  * ownership through json_object_get (& don't forget to do a json_object_put
 202  * or transfer ownership to prevent a memory leak).
 203  *
 204  * @param obj the json_object instance
 205  * @param key the object field name
 206  * @returns the json_object associated with the given field name
 207  * @deprecated Please use json_object_object_get_ex
 208  */
 209 extern struct json_object* json_object_object_get(struct json_object* obj,
 210                                                   const char *key);
 211
 212 /** Get the json_object associated with a given object field.
 213  *
 214  * This returns true if the key is found, false in all other cases (including
 215  * if obj isn't a json_type_object).
 216  *
 217  * *No* reference counts will be changed.  There is no need to manually adjust
 218  * reference counts through the json_object_put/json_object_get methods unless
 219  * you need to have the child (value) reference maintain a different lifetime
 220  * than the owning parent (obj).  Ownership of value is retained by obj.
 221  *
 222  * @param obj the json_object instance
 223  * @param key the object field name
 224  * @param value a pointer where to store a reference to the json_object
 225  *              associated with the given field name.
 226  *
 227  *              It is safe to pass a NULL value.
 228  * @returns whether or not the key exists
 229  */
 230 extern json_bool json_object_object_get_ex(struct json_object* obj,
 231                                                   const char *key,
 232                                                   struct json_object **value);
 233
 234 /** Delete the given json_object field
 235  *
 236  * The reference count will be decremented for the deleted object.  If there
 237  * are no more owners of the value represented by this key, then the value is
 238  * freed.  Otherwise, the reference to the value will remain in memory.
 239  *
 240  * @param obj the json_object instance
 241  * @param key the object field name
 242  */
 243 extern void json_object_object_del(struct json_object* obj, const char *key);
 244
 245 /** Iterate through all keys and values of an object
 246  * @param obj the json_object instance
 247  * @param key the local name for the char* key variable defined in the body
 248  * @param val the local name for the json_object* object variable defined in
 249  *            the body
 250  */
 251 #if defined(__GNUC__) && !defined(__STRICT_ANSI__)
 252
 253 # define json_object_object_foreach(obj,key,val) \
 254  char *key; struct json_object *val; \
 255  for(struct lh_entry *entry = json_object_get_object(obj)->head; ({ if(entry) { key = (char*)entry->k; val = (struct json_object*)entry->v; } ; entry; }); entry = entry->next )
 256
 257 #else /* ANSI C or MSC */
 258
 259 # define json_object_object_foreach(obj,key,val) \
 260  char *key; struct json_object *val; struct lh_entry *entry; \
 261  for(entry = json_object_get_object(obj)->head; (entry ? (key = (char*)entry->k, val = (struct json_object*)entry->v, entry) : 0); entry = entry->next)
 262
 263 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) */
 264
 265 /** Iterate through all keys and values of an object (ANSI C Safe)
 266  * @param obj the json_object instance
 267  * @param iter the object iterator
 268  */
 269 #define json_object_object_foreachC(obj,iter) \
 270  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)
 271
 272 /* Array type methods */
 273
 274 /** Create a new empty json_object of type json_type_array
 275  * @returns a json_object of type json_type_array
 276  */
 277 extern struct json_object* json_object_new_array(void);
 278
 279 /** Get the arraylist of a json_object of type json_type_array
 280  * @param obj the json_object instance
 281  * @returns an arraylist
 282  */
 283 extern struct array_list* json_object_get_array(struct json_object *obj);
 284
 285 /** Get the length of a json_object of type json_type_array
 286  * @param obj the json_object instance
 287  * @returns an int
 288  */
 289 extern int json_object_array_length(struct json_object *obj);
 290
 291 /** Sorts the elements of jso of type json_type_array
 292 *
 293 * Pointers to the json_object pointers will be passed as the two arguments
 294 * to @sort_fn
 295 *
 296 * @param obj the json_object instance
 297 * @param sort_fn a sorting function
 298 */
 299 extern void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *));
 300
 301 /** Add an element to the end of a json_object of type json_type_array
 302  *
 303  * The reference count will *not* be incremented. This is to make adding
 304  * fields to objects in code more compact. If you want to retain a reference
 305  * to an added object you must wrap the passed object with json_object_get
 306  *
 307  * @param obj the json_object instance
 308  * @param val the json_object to be added
 309  */
 310 extern int json_object_array_add(struct json_object *obj,
 311                                  struct json_object *val);
 312
 313 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
 314  *
 315  * The reference count will *not* be incremented. This is to make adding
 316  * fields to objects in code more compact. If you want to retain a reference
 317  * to an added object you must wrap the passed object with json_object_get
 318  *
 319  * The reference count of a replaced object will be decremented.
 320  *
 321  * The array size will be automatically be expanded to the size of the
 322  * index if the index is larger than the current size.
 323  *
 324  * @param obj the json_object instance
 325  * @param idx the index to insert the element at
 326  * @param val the json_object to be added
 327  */
 328 extern int json_object_array_put_idx(struct json_object *obj, int idx,
 329                                      struct json_object *val);
 330
 331 /** Get the element at specificed index of the array (a json_object of type json_type_array)
 332  * @param obj the json_object instance
 333  * @param idx the index to get the element at
 334  * @returns the json_object at the specified index (or NULL)
 335  */
 336 extern struct json_object* json_object_array_get_idx(struct json_object *obj,
 337                                                      int idx);
 338
 339 /* json_bool type methods */
 340
 341 /** Create a new empty json_object of type json_type_boolean
 342  * @param b a json_bool TRUE or FALSE (0 or 1)
 343  * @returns a json_object of type json_type_boolean
 344  */
 345 extern struct json_object* json_object_new_boolean(json_bool b);
 346
 347 /** Get the json_bool value of a json_object
 348  *
 349  * The type is coerced to a json_bool if the passed object is not a json_bool.
 350  * integer and double objects will return FALSE if there value is zero
 351  * or TRUE otherwise. If the passed object is a string it will return
 352  * TRUE if it has a non zero length. If any other object type is passed
 353  * TRUE will be returned if the object is not NULL.
 354  *
 355  * @param obj the json_object instance
 356  * @returns a json_bool
 357  */
 358 extern json_bool json_object_get_boolean(struct json_object *obj);
 359
 360
 361 /* int type methods */
 362
 363 /** Create a new empty json_object of type json_type_int
 364  * Note that values are stored as 64-bit values internally.
 365  * To ensure the full range is maintained, use json_object_new_int64 instead.
 366  * @param i the integer
 367  * @returns a json_object of type json_type_int
 368  */
 369 extern struct json_object* json_object_new_int(int32_t i);
 370
 371
 372 /** Create a new empty json_object of type json_type_int
 373  * @param i the integer
 374  * @returns a json_object of type json_type_int
 375  */
 376 extern struct json_object* json_object_new_int64(int64_t i);
 377
 378
 379 /** Get the int value of a json_object
 380  *
 381  * The type is coerced to a int if the passed object is not a int.
 382  * double objects will return their integer conversion. Strings will be
 383  * parsed as an integer. If no conversion exists then 0 is returned
 384  * and errno is set to EINVAL. null is equivalent to 0 (no error values set)
 385  *
 386  * Note that integers are stored internally as 64-bit values.
 387  * If the value of too big or too small to fit into 32-bit, INT32_MAX or
 388  * INT32_MIN are returned, respectively.
 389  *
 390  * @param obj the json_object instance
 391  * @returns an int
 392  */
 393 extern int32_t json_object_get_int(struct json_object *obj);
 394
 395 /** Get the int value of a json_object
 396  *
 397  * The type is coerced to a int64 if the passed object is not a int64.
 398  * double objects will return their int64 conversion. Strings will be
 399  * parsed as an int64. If no conversion exists then 0 is returned.
 400  *
 401  * NOTE: Set errno to 0 directly before a call to this function to determine
 402  * whether or not conversion was successful (it does not clear the value for
 403  * you).
 404  *
 405  * @param obj the json_object instance
 406  * @returns an int64
 407  */
 408 extern int64_t json_object_get_int64(struct json_object *obj);
 409
 410
 411 /* double type methods */
 412
 413 /** Create a new empty json_object of type json_type_double
 414  * @param d the double
 415  * @returns a json_object of type json_type_double
 416  */
 417 extern struct json_object* json_object_new_double(double d);
 418
 419 /** Get the double floating point value of a json_object
 420  *
 421  * The type is coerced to a double if the passed object is not a double.
 422  * integer objects will return their double conversion. Strings will be
 423  * parsed as a double. If no conversion exists then 0.0 is returned and
 424  * errno is set to EINVAL. null is equivalent to 0 (no error values set)
 425  *
 426  * If the value is too big to fit in a double, then the value is set to
 427  * the closest infinity with errno set to ERANGE. If strings cannot be
 428  * converted to their double value, then EINVAL is set & NaN is returned.
 429  *
 430  * Arrays of length 0 are interpreted as 0 (with no error flags set).
 431  * Arrays of length 1 are effectively cast to the equivalent object and
 432  * converted using the above rules.  All other arrays set the error to
 433  * EINVAL & return NaN.
 434  *
 435  * NOTE: Set errno to 0 directly before a call to this function to
 436  * determine whether or not conversion was successful (it does not clear
 437  * the value for you).
 438  *
 439  * @param obj the json_object instance
 440  * @returns a double floating point number
 441  */
 442 extern double json_object_get_double(struct json_object *obj);
 443
 444
 445 /* string type methods */
 446
 447 /** Create a new empty json_object of type json_type_string
 448  *
 449  * A copy of the string is made and the memory is managed by the json_object
 450  *
 451  * @param s the string
 452  * @returns a json_object of type json_type_string
 453  */
 454 extern struct json_object* json_object_new_string(const char *s);
 455
 456 extern struct json_object* json_object_new_string_len(const char *s, int len);
 457
 458 /** Get the string value of a json_object
 459  *
 460  * If the passed object is not of type json_type_string then the JSON
 461  * representation of the object is returned.
 462  *
 463  * The returned string memory is managed by the json_object and will
 464  * be freed when the reference count of the json_object drops to zero.
 465  *
 466  * @param obj the json_object instance
 467  * @returns a string
 468  */
 469 extern const char* json_object_get_string(struct json_object *obj);
 470
 471 /** Get the string length of a json_object
 472  *
 473  * If the passed object is not of type json_type_string then zero
 474  * will be returned.
 475  *
 476  * @param obj the json_object instance
 477  * @returns int
 478  */
 479 extern int json_object_get_string_len(struct json_object *obj);
 480
 481 #ifdef __cplusplus
 482 }
 483 #endif
 484
 485 #endif