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_
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
21 #define THIS_FUNCTION_IS_DEPRECATED(func) func
24 #include "json_inttypes.h"
30 #define JSON_OBJECT_DEF_HASH_ENTRIES 16
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.
37 #define JSON_C_TO_STRING_PLAIN 0
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.
43 #define JSON_C_TO_STRING_SPACED (1<<0)
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.
49 * See the "Two Space Tab" option at http://jsonformatter.curiousconcept.com/
50 * for an example of the format.
52 #define JSON_C_TO_STRING_PRETTY (1<<1)
54 * A flag to drop trailing zero for float values
56 #define JSON_C_TO_STRING_NOZERO (1<<2)
59 #define FALSE ((json_bool)0)
62 #define TRUE ((json_bool)1)
64 extern const char *json_number_chars
;
65 extern const char *json_hex_chars
;
67 /* CAW: added for ANSI C iteration correctness */
68 struct json_object_iter
71 struct json_object
*val
;
72 struct lh_entry
*entry
;
75 /* forward structure definitions */
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
;
86 * Type of custom user delete functions. See json_object_set_serializer.
88 typedef void (json_object_delete_fn
)(struct json_object
*jso
, void *userdata
);
91 * Type of a custom serialization function. See json_object_set_serializer.
93 typedef int (json_object_to_json_string_fn
)(struct json_object
*jso
,
98 /* supported object types */
100 typedef enum json_type
{
101 /* If you change this, be sure to update json_type_to_name() too */
111 /* reference counting functions */
114 * Increment the reference count of json_object, thereby grabbing shared
117 * @param obj the json_object instance
119 extern struct json_object
* json_object_get(struct json_object
*obj
);
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.
126 * @param obj the json_object instance
127 * @returns 1 if the object was freed.
129 int json_object_put(struct json_object
*obj
);
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),
143 extern int json_object_is_type(struct json_object
*obj
, enum json_type type
);
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.
149 * @param obj the json_object instance
150 * @returns type being one of:
151 json_type_null (i.e. obj == NULL),
159 extern enum json_type
json_object_get_type(struct json_object
*obj
);
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
167 extern const char* json_object_to_json_string(struct json_object
*obj
);
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
174 extern const char* json_object_to_json_string_ext(struct json_object
*obj
, int
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.
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.
184 * If to_string_func is NULL, the other parameters are ignored
185 * and the default behaviour is reset.
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.
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)
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
203 extern void json_object_set_serializer(json_object
*jso
,
204 json_object_to_json_string_fn to_string_func
,
206 json_object_delete_fn
*user_delete
);
209 * Simply call free on the userdata pointer.
210 * Can be used with json_object_set_serializer().
213 * @param userdata the pointer that is passed to free().
215 json_object_delete_fn json_object_free_userdata
;
218 * Copy the jso->_userdata string over to pb as-is.
219 * Can be used with json_object_set_serializer().
221 * @param jso The object whose _userdata is used.
222 * @param pb The destination buffer.
223 * @param level Ignored.
224 * @param flags Ignored.
226 json_object_to_json_string_fn json_object_userdata_to_json_string
;
229 /* object type methods */
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.
239 * @returns a json_object of type json_type_object
241 extern struct json_object
* json_object_new_object(void);
243 /** Get the hashtable of a json_object of type json_type_object
244 * @param obj the json_object instance
245 * @returns a linkhash
247 extern struct lh_table
* json_object_get_object(struct json_object
*obj
);
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
252 extern int json_object_object_length(struct json_object
* obj
);
254 /** Add an object field to a json_object of type json_type_object
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.
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.
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
270 extern void json_object_object_add(struct json_object
* obj
, const char *key
,
271 struct json_object
*val
);
273 /** Get the json_object associate with a given object field
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).
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
290 THIS_FUNCTION_IS_DEPRECATED(extern struct json_object
* json_object_object_get(struct json_object
* obj
,
293 /** Get the json_object associated with a given object field.
295 * This returns true if the key is found, false in all other cases (including
296 * if obj isn't a json_type_object).
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.
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.
308 * It is safe to pass a NULL value.
309 * @returns whether or not the key exists
311 extern json_bool
json_object_object_get_ex(struct json_object
* obj
,
313 struct json_object
**value
);
315 /** Delete the given json_object field
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.
321 * @param obj the json_object instance
322 * @param key the object field name
324 extern void json_object_object_del(struct json_object
* obj
, const char *key
);
327 * Iterate through all keys and values of an object.
329 * Adding keys to the object while iterating is NOT allowed.
331 * Deleting an existing key, or replacing an existing key with a
332 * new value IS allowed.
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
339 #if defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L
341 # define json_object_object_foreach(obj,key,val) \
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 )
352 #else /* ANSI C or MSC */
354 # define json_object_object_foreach(obj,key,val) \
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; \
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)
367 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L */
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
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)
376 /* Array type methods */
378 /** Create a new empty json_object of type json_type_array
379 * @returns a json_object of type json_type_array
381 extern struct json_object
* json_object_new_array(void);
383 /** Get the arraylist of a json_object of type json_type_array
384 * @param obj the json_object instance
385 * @returns an arraylist
387 extern struct array_list
* json_object_get_array(struct json_object
*obj
);
389 /** Get the length of a json_object of type json_type_array
390 * @param obj the json_object instance
393 extern int json_object_array_length(struct json_object
*obj
);
395 /** Sorts the elements of jso of type json_type_array
397 * Pointers to the json_object pointers will be passed as the two arguments
400 * @param obj the json_object instance
401 * @param sort_fn a sorting function
403 extern void json_object_array_sort(struct json_object
*jso
, int(*sort_fn
)(const void *, const void *));
405 /** Add an element to the end of a json_object of type json_type_array
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
411 * @param obj the json_object instance
412 * @param val the json_object to be added
414 extern int json_object_array_add(struct json_object
*obj
,
415 struct json_object
*val
);
417 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
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
423 * The reference count of a replaced object will be decremented.
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.
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
432 extern int json_object_array_put_idx(struct json_object
*obj
, int idx
,
433 struct json_object
*val
);
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)
440 extern struct json_object
* json_object_array_get_idx(struct json_object
*obj
,
443 /* json_bool type methods */
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
449 extern struct json_object
* json_object_new_boolean(json_bool b
);
451 /** Get the json_bool value of a json_object
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.
459 * @param obj the json_object instance
460 * @returns a json_bool
462 extern json_bool
json_object_get_boolean(struct json_object
*obj
);
465 /* int type methods */
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
473 extern struct json_object
* json_object_new_int(int32_t i
);
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
480 extern struct json_object
* json_object_new_int64(int64_t i
);
483 /** Get the int value of a json_object
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)
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.
494 * @param obj the json_object instance
497 extern int32_t json_object_get_int(struct json_object
*obj
);
499 /** Get the int value of a json_object
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.
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
509 * @param obj the json_object instance
512 extern int64_t json_object_get_int64(struct json_object
*obj
);
515 /* double type methods */
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
521 extern struct json_object
* json_object_new_double(double d
);
524 * Create a new json_object of type json_type_double, using
525 * the exact serialized representation of the value.
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.
531 * Note: this is used by json_tokener_parse_ex() to allow for
532 * an exact re-serialization of a parsed object.
534 * An equivalent sequence of calls is:
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)
541 * @param d the numeric value of the double.
542 * @param ds the string representation of the double. This will be copied.
544 extern struct json_object
* json_object_new_double_s(double d
, const char *ds
);
546 /** Get the double floating point value of a json_object
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)
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.
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.
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).
566 * @param obj the json_object instance
567 * @returns a double floating point number
569 extern double json_object_get_double(struct json_object
*obj
);
572 /* string type methods */
574 /** Create a new empty json_object of type json_type_string
576 * A copy of the string is made and the memory is managed by the json_object
578 * @param s the string
579 * @returns a json_object of type json_type_string
581 extern struct json_object
* json_object_new_string(const char *s
);
583 extern struct json_object
* json_object_new_string_len(const char *s
, int len
);
585 /** Get the string value of a json_object
587 * If the passed object is not of type json_type_string then the JSON
588 * representation of the object is returned.
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.
593 * @param obj the json_object instance
596 extern const char* json_object_get_string(struct json_object
*obj
);
598 /** Get the string length of a json_object
600 * If the passed object is not of type json_type_string then zero
603 * @param obj the json_object instance
606 extern int json_object_get_string_len(struct json_object
*obj
);