2 * $Id: json_object.h,v 1.12 2006/01/30 23:07:57 mclark Exp $
4 * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
5 * Michael Clark <michael@metaparadigm.com>
6 * Copyright (c) 2009 Hewlett-Packard Development Company, L.P.
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.
13 #ifndef _json_object_h_
14 #define _json_object_h_
16 #include "json_inttypes.h"
22 #define JSON_OBJECT_DEF_HASH_ENTRIES 16
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.
29 #define JSON_C_TO_STRING_PLAIN 0
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.
35 #define JSON_C_TO_STRING_SPACED (1<<0)
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.
41 * See the "Two Space Tab" option at http://jsonformatter.curiousconcept.com/
42 * for an example of the format.
44 #define JSON_C_TO_STRING_PRETTY (1<<1)
47 #define FALSE ((json_bool)0)
50 #define TRUE ((json_bool)1)
52 extern const char *json_number_chars;
53 extern const char *json_hex_chars;
55 /* CAW: added for ANSI C iteration correctness */
56 struct json_object_iter
59 struct json_object *val;
60 struct lh_entry *entry;
63 /* forward structure definitions */
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;
74 * Type of custom user delete functions. See json_object_set_serializer.
76 typedef void (json_object_delete_fn)(struct json_object *jso, void *userdata);
79 * Type of a custom serialization function. See json_object_set_serializer.
81 typedef int (json_object_to_json_string_fn)(struct json_object *jso,
86 /* supported object types */
88 typedef enum json_type {
89 /* If you change this, be sure to update json_type_to_name() too */
99 /* reference counting functions */
102 * Increment the reference count of json_object, thereby grabbing shared
105 * @param obj the json_object instance
107 extern struct json_object* json_object_get(struct json_object *obj);
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.
114 * @param obj the json_object instance
115 * @returns 1 if the object was freed.
117 int json_object_put(struct json_object *obj);
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),
131 extern int json_object_is_type(struct json_object *obj, enum json_type type);
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.
137 * @param obj the json_object instance
138 * @returns type being one of:
139 json_type_null (i.e. obj == NULL),
147 extern enum json_type json_object_get_type(struct json_object *obj);
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
155 extern const char* json_object_to_json_string(struct json_object *obj);
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
162 extern const char* json_object_to_json_string_ext(struct json_object *obj, int
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.
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.
172 * If to_string_func is NULL, the other parameters are ignored
173 * and the default behaviour is reset.
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.
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)
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
191 void json_object_set_serializer(json_object *jso,
192 json_object_to_json_string_fn to_string_func,
194 json_object_delete_fn *user_delete);
198 /* object type methods */
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.
208 * @returns a json_object of type json_type_object
210 extern struct json_object* json_object_new_object(void);
212 /** Get the hashtable of a json_object of type json_type_object
213 * @param obj the json_object instance
214 * @returns a linkhash
216 extern struct lh_table* json_object_get_object(struct json_object *obj);
218 /** Add an object field to a json_object of type json_type_object
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.
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.
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
234 extern void json_object_object_add(struct json_object* obj, const char *key,
235 struct json_object *val);
237 /** Get the json_object associate with a given object field
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).
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
254 extern struct json_object* json_object_object_get(struct json_object* obj,
257 /** Get the json_object associated with a given object field.
259 * This returns true if the key is found, false in all other cases (including
260 * if obj isn't a json_type_object).
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.
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.
272 * It is safe to pass a NULL value.
273 * @returns whether or not the key exists
275 extern json_bool json_object_object_get_ex(struct json_object* obj,
277 struct json_object **value);
279 /** Delete the given json_object field
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.
285 * @param obj the json_object instance
286 * @param key the object field name
288 extern void json_object_object_del(struct json_object* obj, const char *key);
291 * Iterate through all keys and values of an object.
293 * Adding keys to the object while iterating is NOT allowed.
295 * Deleting an existing key, or replacing an existing key with a
296 * new value IS allowed.
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
303 #if defined(__GNUC__) && !defined(__STRICT_ANSI__)
305 # define json_object_object_foreach(obj,key,val) \
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 )
316 #else /* ANSI C or MSC */
318 # define json_object_object_foreach(obj,key,val) \
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; \
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)
331 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) */
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
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)
340 /* Array type methods */
342 /** Create a new empty json_object of type json_type_array
343 * @returns a json_object of type json_type_array
345 extern struct json_object* json_object_new_array(void);
347 /** Get the arraylist of a json_object of type json_type_array
348 * @param obj the json_object instance
349 * @returns an arraylist
351 extern struct array_list* json_object_get_array(struct json_object *obj);
353 /** Get the length of a json_object of type json_type_array
354 * @param obj the json_object instance
357 extern int json_object_array_length(struct json_object *obj);
359 /** Sorts the elements of jso of type json_type_array
361 * Pointers to the json_object pointers will be passed as the two arguments
364 * @param obj the json_object instance
365 * @param sort_fn a sorting function
367 extern void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *));
369 /** Add an element to the end of a json_object of type json_type_array
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
375 * @param obj the json_object instance
376 * @param val the json_object to be added
378 extern int json_object_array_add(struct json_object *obj,
379 struct json_object *val);
381 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
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
387 * The reference count of a replaced object will be decremented.
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.
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
396 extern int json_object_array_put_idx(struct json_object *obj, int idx,
397 struct json_object *val);
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)
404 extern struct json_object* json_object_array_get_idx(struct json_object *obj,
407 /* json_bool type methods */
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
413 extern struct json_object* json_object_new_boolean(json_bool b);
415 /** Get the json_bool value of a json_object
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.
423 * @param obj the json_object instance
424 * @returns a json_bool
426 extern json_bool json_object_get_boolean(struct json_object *obj);
429 /* int type methods */
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
437 extern struct json_object* json_object_new_int(int32_t i);
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
444 extern struct json_object* json_object_new_int64(int64_t i);
447 /** Get the int value of a json_object
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)
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.
458 * @param obj the json_object instance
461 extern int32_t json_object_get_int(struct json_object *obj);
463 /** Get the int value of a json_object
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.
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
473 * @param obj the json_object instance
476 extern int64_t json_object_get_int64(struct json_object *obj);
479 /* double type methods */
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
485 extern struct json_object* json_object_new_double(double d);
487 /** Get the double floating point value of a json_object
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)
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.
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.
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).
507 * @param obj the json_object instance
508 * @returns a double floating point number
510 extern double json_object_get_double(struct json_object *obj);
513 /* string type methods */
515 /** Create a new empty json_object of type json_type_string
517 * A copy of the string is made and the memory is managed by the json_object
519 * @param s the string
520 * @returns a json_object of type json_type_string
522 extern struct json_object* json_object_new_string(const char *s);
524 extern struct json_object* json_object_new_string_len(const char *s, int len);
526 /** Get the string value of a json_object
528 * If the passed object is not of type json_type_string then the JSON
529 * representation of the object is returned.
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.
534 * @param obj the json_object instance
537 extern const char* json_object_get_string(struct json_object *obj);
539 /** Get the string length of a json_object
541 * If the passed object is not of type json_type_string then zero
544 * @param obj the json_object instance
547 extern int json_object_get_string_len(struct json_object *obj);