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.
15 * @brief Core json-c API. Start here, or with json_tokener.h
17 #ifndef _json_object_h_
18 #define _json_object_h_
21 #define THIS_FUNCTION_IS_DEPRECATED(func) func __attribute__ ((deprecated))
22 #elif defined(_MSC_VER)
23 #define THIS_FUNCTION_IS_DEPRECATED(func) __declspec(deprecated) func
24 #elif defined(__clang__)
25 #define THIS_FUNCTION_IS_DEPRECATED(func) func __deprecated
27 #define THIS_FUNCTION_IS_DEPRECATED(func) func
31 #define JSON_C_CONST_FUNCTION(func) func __attribute__((const))
33 #define JSON_C_CONST_FUNCTION(func) func
37 #define JSON_EXPORT __declspec(dllexport)
39 #define JSON_EXPORT extern
43 #include "json_inttypes.h"
50 #define JSON_OBJECT_DEF_HASH_ENTRIES 16
53 * A flag for the json_object_to_json_string_ext() and
54 * json_object_to_file_ext() functions which causes the output
55 * to have no extra whitespace or formatting applied.
57 #define JSON_C_TO_STRING_PLAIN 0
59 * A flag for the json_object_to_json_string_ext() and
60 * json_object_to_file_ext() functions which causes the output to have
61 * minimal whitespace inserted to make things slightly more readable.
63 #define JSON_C_TO_STRING_SPACED (1<<0)
65 * A flag for the json_object_to_json_string_ext() and
66 * json_object_to_file_ext() functions which causes
67 * the output to be formatted.
69 * See the "Two Space Tab" option at http://jsonformatter.curiousconcept.com/
70 * for an example of the format.
72 #define JSON_C_TO_STRING_PRETTY (1<<1)
74 * A flag for the json_object_to_json_string_ext() and
75 * json_object_to_file_ext() functions which causes
76 * the output to be formatted.
78 * Instead of a "Two Space Tab" this gives a single tab character.
80 #define JSON_C_TO_STRING_PRETTY_TAB (1<<3)
82 * A flag to drop trailing zero for float values
84 #define JSON_C_TO_STRING_NOZERO (1<<2)
87 * Don't escape forward slashes.
89 #define JSON_C_TO_STRING_NOSLASHESCAPE (1<<4)
92 * A flag for the json_object_object_add_ex function which
93 * causes the value to be added without a check if it already exists.
94 * Note: it is the responsibilty of the caller to ensure that no
95 * key is added multiple times. If this is done, results are
96 * unpredictable. While this option is somewhat dangerous, it
97 * permits potentially large performance savings in code that
98 * knows for sure the key values are unique (e.g. because the
99 * code adds a well-known set of constant key values).
101 #define JSON_C_OBJECT_ADD_KEY_IS_NEW (1<<1)
103 * A flag for the json_object_object_add_ex function which
104 * flags the key as being constant memory. This means that
105 * the key will NOT be copied via strdup(), resulting in a
106 * potentially huge performance win (malloc, strdup and
107 * free are usually performance hogs). It is acceptable to
108 * use this flag for keys in non-constant memory blocks if
109 * the caller ensure that the memory holding the key lives
110 * longer than the corresponding json object. However, this
111 * is somewhat dangerous and should only be done if really
113 * The general use-case for this flag is cases where the
114 * key is given as a real constant value in the function
116 * json_object_object_add_ex(obj, "ip", json,
117 * JSON_C_OBJECT_KEY_IS_CONSTANT);
119 #define JSON_C_OBJECT_KEY_IS_CONSTANT (1<<2)
122 #define FALSE ((json_bool)0)
125 #define TRUE ((json_bool)1)
128 * Set the global value of an option, which will apply to all
129 * current and future threads that have not set a thread-local value.
131 * @see json_c_set_serialization_double_format
133 #define JSON_C_OPTION_GLOBAL (0)
135 * Set a thread-local value of an option, overriding the global value.
136 * This will fail if json-c is not compiled with threading enabled, and
137 * with the __thread specifier (or equivalent) available.
139 * @see json_c_set_serialization_double_format
141 #define JSON_C_OPTION_THREAD (1)
144 * A structure to use with json_object_object_foreachC() loops.
145 * Contains key, val and entry members.
147 struct json_object_iter
150 struct json_object *val;
151 struct lh_entry *entry;
153 typedef struct json_object_iter json_object_iter;
155 typedef int json_bool;
158 * @brief The core type for all type of JSON objects handled by json-c
160 typedef struct json_object json_object;
163 * Type of custom user delete functions. See json_object_set_serializer.
165 typedef void (json_object_delete_fn)(struct json_object *jso, void *userdata);
168 * Type of a custom serialization function. See json_object_set_serializer.
170 typedef int (json_object_to_json_string_fn)(struct json_object *jso,
175 /* supported object types */
177 typedef enum json_type {
178 /* If you change this, be sure to update json_type_to_name() too */
188 /* reference counting functions */
191 * Increment the reference count of json_object, thereby grabbing shared
194 * @param obj the json_object instance
196 JSON_EXPORT struct json_object* json_object_get(struct json_object *obj);
199 * Decrement the reference count of json_object and free if it reaches zero.
200 * You must have ownership of obj prior to doing this or you will cause an
201 * imbalance in the reference count.
203 * @param obj the json_object instance
204 * @returns 1 if the object was freed.
206 JSON_EXPORT int json_object_put(struct json_object *obj);
209 * Check if the json_object is of a given type
210 * @param obj the json_object instance
211 * @param type one of:
212 json_type_null (i.e. obj == NULL),
220 JSON_EXPORT int json_object_is_type(const struct json_object *obj, enum json_type type);
223 * Get the type of the json_object. See also json_type_to_name() to turn this
224 * into a string suitable, for instance, for logging.
226 * @param obj the json_object instance
227 * @returns type being one of:
228 json_type_null (i.e. obj == NULL),
236 #define json_object_get_type _json_object_get_type
237 JSON_EXPORT enum json_type _json_object_get_type(const struct json_object *obj);
240 /** Stringify object to json format.
241 * Equivalent to json_object_to_json_string_ext(obj, JSON_C_TO_STRING_SPACED)
242 * The pointer you get is an internal of your json object. You don't
243 * have to free it, later use of json_object_put() should be sufficient.
244 * If you can not ensure there's no concurrent access to *obj use
246 * @param obj the json_object instance
247 * @returns a string in JSON format
249 JSON_EXPORT const char* json_object_to_json_string(struct json_object *obj);
251 /** Stringify object to json format
252 * @see json_object_to_json_string() for details on how to free string.
253 * @param obj the json_object instance
254 * @param flags formatting options, see JSON_C_TO_STRING_PRETTY and other constants
255 * @returns a string in JSON format
257 JSON_EXPORT const char* json_object_to_json_string_ext(struct json_object *obj, int
260 /** Stringify object to json format
261 * @see json_object_to_json_string() for details on how to free string.
262 * @param obj the json_object instance
263 * @param flags formatting options, see JSON_C_TO_STRING_PRETTY and other constants
264 * @param length a pointer where, if not NULL, the length (without null) is stored
265 * @returns a string in JSON format and the length if not NULL
267 JSON_EXPORT const char* json_object_to_json_string_length(struct json_object *obj, int
268 flags, size_t *length);
271 * Returns the userdata set by json_object_set_userdata() or
272 * json_object_set_serializer()
274 * @param jso the object to return the userdata for
276 JSON_EXPORT void* json_object_get_userdata(json_object *jso);
279 * Set an opaque userdata value for an object
281 * The userdata can be retrieved using json_object_get_userdata().
283 * If custom userdata is already set on this object, any existing user_delete
284 * function is called before the new one is set.
286 * The user_delete parameter is optional and may be passed as NULL, even if
287 * the userdata parameter is non-NULL. It will be called just before the
288 * json_object is deleted, after it's reference count goes to zero
289 * (see json_object_put()).
290 * If this is not provided, it is up to the caller to free the userdata at
291 * an appropriate time. (i.e. after the json_object is deleted)
293 * Note: Objects created by parsing strings may have custom serializers set
294 * which expect the userdata to contain specific data (due to use of
295 * json_object_new_double_s()). In this case, json_object_set_serialiser() with
296 * NULL as to_string_func should be used instead to set the userdata and reset
297 * the serializer to its default value.
299 * @param jso the object to set the userdata for
300 * @param userdata an optional opaque cookie
301 * @param user_delete an optional function from freeing userdata
303 JSON_EXPORT void json_object_set_userdata(json_object *jso, void *userdata,
304 json_object_delete_fn *user_delete);
307 * Set a custom serialization function to be used when this particular object
308 * is converted to a string by json_object_to_json_string.
310 * If custom userdata is already set on this object, any existing user_delete
311 * function is called before the new one is set.
313 * If to_string_func is NULL the default behaviour is reset (but the userdata
314 * and user_delete fields are still set).
316 * The userdata parameter is optional and may be passed as NULL. It can be used
317 * to provide additional data for to_string_func to use. This parameter may
318 * be NULL even if user_delete is non-NULL.
320 * The user_delete parameter is optional and may be passed as NULL, even if
321 * the userdata parameter is non-NULL. It will be called just before the
322 * json_object is deleted, after it's reference count goes to zero
323 * (see json_object_put()).
324 * If this is not provided, it is up to the caller to free the userdata at
325 * an appropriate time. (i.e. after the json_object is deleted)
327 * Note that the userdata is the same as set by json_object_set_userdata(), so
328 * care must be taken not to overwrite the value when both a custom serializer
329 * and json_object_set_userdata() are used.
331 * @param jso the object to customize
332 * @param to_string_func the custom serialization function
333 * @param userdata an optional opaque cookie
334 * @param user_delete an optional function from freeing userdata
336 JSON_EXPORT void json_object_set_serializer(json_object *jso,
337 json_object_to_json_string_fn *to_string_func,
339 json_object_delete_fn *user_delete);
343 * Clang doesn't pay attention to the parameters defined in the
344 * function typedefs used here, so turn off spurious doc warnings.
347 #pragma clang diagnostic push
348 #pragma clang diagnostic ignored "-Wdocumentation"
352 * Simply call free on the userdata pointer.
353 * Can be used with json_object_set_serializer().
356 * @param userdata the pointer that is passed to free().
358 json_object_delete_fn json_object_free_userdata;
361 * Copy the jso->_userdata string over to pb as-is.
362 * Can be used with json_object_set_serializer().
364 * @param jso The object whose _userdata is used.
365 * @param pb The destination buffer.
366 * @param level Ignored.
367 * @param flags Ignored.
369 json_object_to_json_string_fn json_object_userdata_to_json_string;
373 #pragma clang diagnostic pop
377 /* object type methods */
379 /** Create a new empty object with a reference count of 1. The caller of
380 * this object initially has sole ownership. Remember, when using
381 * json_object_object_add or json_object_array_put_idx, ownership will
382 * transfer to the object/array. Call json_object_get if you want to maintain
383 * shared ownership or also add this object as a child of multiple objects or
384 * arrays. Any ownerships you acquired but did not transfer must be released
385 * through json_object_put.
387 * @returns a json_object of type json_type_object
389 JSON_EXPORT struct json_object* json_object_new_object(void);
391 /** Get the hashtable of a json_object of type json_type_object
392 * @param obj the json_object instance
393 * @returns a linkhash
395 JSON_EXPORT struct lh_table* json_object_get_object(const struct json_object *obj);
397 /** Get the size of an object in terms of the number of fields it has.
398 * @param obj the json_object whose length to return
400 JSON_EXPORT int json_object_object_length(const struct json_object* obj);
402 /** Get the sizeof (struct json_object).
403 * @returns a size_t with the sizeof (struct json_object)
405 JSON_C_CONST_FUNCTION(JSON_EXPORT size_t json_c_object_sizeof(void));
407 /** Add an object field to a json_object of type json_type_object
409 * The reference count will *not* be incremented. This is to make adding
410 * fields to objects in code more compact. If you want to retain a reference
411 * to an added object, independent of the lifetime of obj, you must wrap the
412 * passed object with json_object_get.
414 * Upon calling this, the ownership of val transfers to obj. Thus you must
415 * make sure that you do in fact have ownership over this object. For instance,
416 * json_object_new_object will give you ownership until you transfer it,
417 * whereas json_object_object_get does not.
419 * @param obj the json_object instance
420 * @param key the object field name (a private copy will be duplicated)
421 * @param val a json_object or NULL member to associate with the given field
423 * @return On success, <code>0</code> is returned.
424 * On error, a negative value is returned.
426 JSON_EXPORT int json_object_object_add(struct json_object* obj, const char *key,
427 struct json_object *val);
429 /** Add an object field to a json_object of type json_type_object
431 * The semantics are identical to json_object_object_add, except that an
432 * additional flag fields gives you more control over some detail aspects
433 * of processing. See the description of JSON_C_OBJECT_ADD_* flags for more
436 * @param obj the json_object instance
437 * @param key the object field name (a private copy will be duplicated)
438 * @param val a json_object or NULL member to associate with the given field
439 * @param opts process-modifying options. To specify multiple options, use
440 * arithmetic or (OPT1|OPT2)
442 JSON_EXPORT int json_object_object_add_ex(struct json_object* obj,
443 const char *const key,
444 struct json_object *const val,
445 const unsigned opts);
447 /** Get the json_object associate with a given object field.
448 * Deprecated/discouraged: used json_object_object_get_ex instead.
450 * This returns NULL if the field is found but its value is null, or if
451 * the field is not found, or if obj is not a json_type_object. If you
452 * need to distinguis between these cases, use json_object_object_get_ex().
454 * *No* reference counts will be changed. There is no need to manually adjust
455 * reference counts through the json_object_put/json_object_get methods unless
456 * you need to have the child (value) reference maintain a different lifetime
457 * than the owning parent (obj). Ownership of the returned value is retained
458 * by obj (do not do json_object_put unless you have done a json_object_get).
459 * If you delete the value from obj (json_object_object_del) and wish to access
460 * the returned reference afterwards, make sure you have first gotten shared
461 * ownership through json_object_get (& don't forget to do a json_object_put
462 * or transfer ownership to prevent a memory leak).
464 * @param obj the json_object instance
465 * @param key the object field name
466 * @returns the json_object associated with the given field name
468 JSON_EXPORT struct json_object* json_object_object_get(const struct json_object* obj,
471 /** Get the json_object associated with a given object field.
473 * This returns true if the key is found, false in all other cases (including
474 * if obj isn't a json_type_object).
476 * *No* reference counts will be changed. There is no need to manually adjust
477 * reference counts through the json_object_put/json_object_get methods unless
478 * you need to have the child (value) reference maintain a different lifetime
479 * than the owning parent (obj). Ownership of value is retained by obj.
481 * @param obj the json_object instance
482 * @param key the object field name
483 * @param value a pointer where to store a reference to the json_object
484 * associated with the given field name.
486 * It is safe to pass a NULL value.
487 * @returns whether or not the key exists
489 JSON_EXPORT json_bool json_object_object_get_ex(const struct json_object* obj,
491 struct json_object **value);
493 /** Delete the given json_object field
495 * The reference count will be decremented for the deleted object. If there
496 * are no more owners of the value represented by this key, then the value is
497 * freed. Otherwise, the reference to the value will remain in memory.
499 * @param obj the json_object instance
500 * @param key the object field name
502 JSON_EXPORT void json_object_object_del(struct json_object* obj, const char *key);
505 * Iterate through all keys and values of an object.
507 * Adding keys to the object while iterating is NOT allowed.
509 * Deleting an existing key, or replacing an existing key with a
510 * new value IS allowed.
512 * @param obj the json_object instance
513 * @param key the local name for the char* key variable defined in the body
514 * @param val the local name for the json_object* object variable defined in
517 #if defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L
519 # define json_object_object_foreach(obj,key,val) \
521 struct json_object *val __attribute__((__unused__)) = NULL; \
522 for(struct lh_entry *entry ## key = json_object_get_object(obj)->head, *entry_next ## key = NULL; \
523 ({ if(entry ## key) { \
524 key = (char*)lh_entry_k(entry ## key); \
525 val = (struct json_object*)lh_entry_v(entry ## key); \
526 entry_next ## key = entry ## key->next; \
527 } ; entry ## key; }); \
528 entry ## key = entry_next ## key )
530 #else /* ANSI C or MSC */
532 # define json_object_object_foreach(obj,key,val) \
534 struct json_object *val = NULL; \
535 struct lh_entry *entry ## key; \
536 struct lh_entry *entry_next ## key = NULL; \
537 for(entry ## key = json_object_get_object(obj)->head; \
539 key = (char*)lh_entry_k(entry ## key), \
540 val = (struct json_object*)lh_entry_v(entry ## key), \
541 entry_next ## key = entry ## key->next, \
542 entry ## key) : 0); \
543 entry ## key = entry_next ## key)
545 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L */
547 /** Iterate through all keys and values of an object (ANSI C Safe)
548 * @param obj the json_object instance
549 * @param iter the object iterator, use type json_object_iter
551 #define json_object_object_foreachC(obj,iter) \
552 for(iter.entry = json_object_get_object(obj)->head; \
553 (iter.entry ? (iter.key = (char*)lh_entry_k(iter.entry), iter.val = (struct json_object*)lh_entry_v(iter.entry), iter.entry) : 0); \
554 iter.entry = iter.entry->next)
556 /* Array type methods */
558 /** Create a new empty json_object of type json_type_array
559 * @returns a json_object of type json_type_array
561 JSON_EXPORT struct json_object* json_object_new_array(void);
563 /** Get the arraylist of a json_object of type json_type_array
564 * @param obj the json_object instance
565 * @returns an arraylist
567 JSON_EXPORT struct array_list* json_object_get_array(const struct json_object *obj);
569 /** Get the length of a json_object of type json_type_array
570 * @param obj the json_object instance
573 JSON_EXPORT size_t json_object_array_length(const struct json_object *obj);
575 /** Sorts the elements of jso of type json_type_array
577 * Pointers to the json_object pointers will be passed as the two arguments
580 * @param jso the json_object instance
581 * @param sort_fn a sorting function
583 JSON_EXPORT void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *));
585 /** Binary search a sorted array for a specified key object.
587 * It depends on your compare function what's sufficient as a key.
588 * Usually you create some dummy object with the parameter compared in
589 * it, to identify the right item you're actually looking for.
591 * @see json_object_array_sort() for hints on the compare function.
593 * @param key a dummy json_object with the right key
594 * @param jso the array object we're searching
595 * @param sort_fn the sort/compare function
597 * @return the wanted json_object instance
599 JSON_EXPORT struct json_object* json_object_array_bsearch(
600 const struct json_object *key,
601 const struct json_object *jso,
602 int (*sort_fn)(const void *, const void *));
604 /** Add an element to the end of a json_object of type json_type_array
606 * The reference count will *not* be incremented. This is to make adding
607 * fields to objects in code more compact. If you want to retain a reference
608 * to an added object you must wrap the passed object with json_object_get
610 * @param obj the json_object instance
611 * @param val the json_object to be added
613 JSON_EXPORT int json_object_array_add(struct json_object *obj,
614 struct json_object *val);
616 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
618 * The reference count will *not* be incremented. This is to make adding
619 * fields to objects in code more compact. If you want to retain a reference
620 * to an added object you must wrap the passed object with json_object_get
622 * The reference count of a replaced object will be decremented.
624 * The array size will be automatically be expanded to the size of the
625 * index if the index is larger than the current size.
627 * @param obj the json_object instance
628 * @param idx the index to insert the element at
629 * @param val the json_object to be added
631 JSON_EXPORT int json_object_array_put_idx(struct json_object *obj, size_t idx,
632 struct json_object *val);
634 /** Get the element at specificed index of the array (a json_object of type json_type_array)
635 * @param obj the json_object instance
636 * @param idx the index to get the element at
637 * @returns the json_object at the specified index (or NULL)
639 JSON_EXPORT struct json_object* json_object_array_get_idx(const struct json_object *obj,
642 /** Delete an elements from a specified index in an array (a json_object of type json_type_array)
644 * The reference count will be decremented for each of the deleted objects. If there
645 * are no more owners of an element that is being deleted, then the value is
646 * freed. Otherwise, the reference to the value will remain in memory.
648 * @param obj the json_object instance
649 * @param idx the index to start deleting elements at
650 * @param count the number of elements to delete
651 * @returns 0 if the elements were successfully deleted
653 JSON_EXPORT int json_object_array_del_idx(struct json_object *obj, size_t idx, size_t count);
655 /* json_bool type methods */
657 /** Create a new empty json_object of type json_type_boolean
658 * @param b a json_bool TRUE or FALSE (1 or 0)
659 * @returns a json_object of type json_type_boolean
661 JSON_EXPORT struct json_object* json_object_new_boolean(json_bool b);
663 /** Get the json_bool value of a json_object
665 * The type is coerced to a json_bool if the passed object is not a json_bool.
666 * integer and double objects will return FALSE if there value is zero
667 * or TRUE otherwise. If the passed object is a string it will return
668 * TRUE if it has a non zero length. If any other object type is passed
669 * TRUE will be returned if the object is not NULL.
671 * @param obj the json_object instance
672 * @returns a json_bool
674 JSON_EXPORT json_bool json_object_get_boolean(const struct json_object *obj);
677 /** Set the json_bool value of a json_object
679 * The type of obj is checked to be a json_type_boolean and 0 is returned
680 * if it is not without any further actions. If type of obj is json_type_boolean
681 * the obect value is chaned to new_value
683 * @param obj the json_object instance
684 * @param new_value the value to be set
685 * @returns 1 if value is set correctly, 0 otherwise
687 JSON_EXPORT int json_object_set_boolean(struct json_object *obj,json_bool new_value);
690 /* int type methods */
692 /** Create a new empty json_object of type json_type_int
693 * Note that values are stored as 64-bit values internally.
694 * To ensure the full range is maintained, use json_object_new_int64 instead.
695 * @param i the integer
696 * @returns a json_object of type json_type_int
698 JSON_EXPORT struct json_object* json_object_new_int(int32_t i);
701 /** Create a new empty json_object of type json_type_int
702 * @param i the integer
703 * @returns a json_object of type json_type_int
705 JSON_EXPORT struct json_object* json_object_new_int64(int64_t i);
708 /** Get the int value of a json_object
710 * The type is coerced to a int if the passed object is not a int.
711 * double objects will return their integer conversion. Strings will be
712 * parsed as an integer. If no conversion exists then 0 is returned
713 * and errno is set to EINVAL. null is equivalent to 0 (no error values set)
715 * Note that integers are stored internally as 64-bit values.
716 * If the value of too big or too small to fit into 32-bit, INT32_MAX or
717 * INT32_MIN are returned, respectively.
719 * @param obj the json_object instance
722 JSON_EXPORT int32_t json_object_get_int(const struct json_object *obj);
724 /** Set the int value of a json_object
726 * The type of obj is checked to be a json_type_int and 0 is returned
727 * if it is not without any further actions. If type of obj is json_type_int
728 * the obect value is changed to new_value
730 * @param obj the json_object instance
731 * @param new_value the value to be set
732 * @returns 1 if value is set correctly, 0 otherwise
734 JSON_EXPORT int json_object_set_int(struct json_object *obj,int new_value);
736 /** Increment a json_type_int object by the given amount, which may be negative.
738 * If the type of obj is not json_type_int then 0 is returned with no further
740 * If the addition would result in a overflow, the object value
741 * is set to INT64_MAX.
742 * If the addition would result in a underflow, the object value
743 * is set to INT64_MIN.
744 * Neither overflow nor underflow affect the return value.
746 * @param obj the json_object instance
747 * @param val the value to add
748 * @returns 1 if the increment succeded, 0 otherwise
750 JSON_EXPORT int json_object_int_inc(struct json_object *obj, int64_t val);
753 /** Get the int value of a json_object
755 * The type is coerced to a int64 if the passed object is not a int64.
756 * double objects will return their int64 conversion. Strings will be
757 * parsed as an int64. If no conversion exists then 0 is returned.
759 * NOTE: Set errno to 0 directly before a call to this function to determine
760 * whether or not conversion was successful (it does not clear the value for
763 * @param obj the json_object instance
766 JSON_EXPORT int64_t json_object_get_int64(const struct json_object *obj);
769 /** Set the int64_t value of a json_object
771 * The type of obj is checked to be a json_type_int and 0 is returned
772 * if it is not without any further actions. If type of obj is json_type_int
773 * the obect value is chaned to new_value
775 * @param obj the json_object instance
776 * @param new_value the value to be set
777 * @returns 1 if value is set correctly, 0 otherwise
779 JSON_EXPORT int json_object_set_int64(struct json_object *obj,int64_t new_value);
781 /* double type methods */
783 /** Create a new empty json_object of type json_type_double
785 * @see json_object_double_to_json_string() for how to set a custom format string.
787 * @param d the double
788 * @returns a json_object of type json_type_double
790 JSON_EXPORT struct json_object* json_object_new_double(double d);
793 * Create a new json_object of type json_type_double, using
794 * the exact serialized representation of the value.
796 * This allows for numbers that would otherwise get displayed
797 * inefficiently (e.g. 12.3 => "12.300000000000001") to be
798 * serialized with the more convenient form.
802 * This is used by json_tokener_parse_ex() to allow for
803 * an exact re-serialization of a parsed object.
805 * The userdata field is used to store the string representation, so it
806 * can't be used for other data if this function is used.
808 * An equivalent sequence of calls is:
810 * jso = json_object_new_double(d);
811 * json_object_set_serializer(jso, json_object_userdata_to_json_string,
812 * strdup(ds), json_object_free_userdata);
815 * @param d the numeric value of the double.
816 * @param ds the string representation of the double. This will be copied.
818 JSON_EXPORT struct json_object* json_object_new_double_s(double d, const char *ds);
821 * Set a global or thread-local json-c option, depending on whether
822 * JSON_C_OPTION_GLOBAL or JSON_C_OPTION_THREAD is passed.
823 * Thread-local options default to undefined, and inherit from the global
824 * value, even if the global value is changed after the thread is created.
825 * Attempting to set thread-local options when threading is not compiled in
826 * will result in an error. Be sure to check the return value.
828 * double_format is a "%g" printf format, such as "%.20g"
830 * @return -1 on errors, 0 on success.
832 int json_c_set_serialization_double_format(const char *double_format, int global_or_thread);
836 /** Serialize a json_object of type json_type_double to a string.
838 * This function isn't meant to be called directly. Instead, you can set a
839 * custom format string for the serialization of this double using the
840 * following call (where "%.17g" actually is the default):
843 * jso = json_object_new_double(d);
844 * json_object_set_serializer(jso, json_object_double_to_json_string,
848 * @see printf(3) man page for format strings
850 * @param jso The json_type_double object that is serialized.
851 * @param pb The destination buffer.
852 * @param level Ignored.
853 * @param flags Ignored.
855 JSON_EXPORT int json_object_double_to_json_string(struct json_object* jso,
860 /** Get the double floating point value of a json_object
862 * The type is coerced to a double if the passed object is not a double.
863 * integer objects will return their double conversion. Strings will be
864 * parsed as a double. If no conversion exists then 0.0 is returned and
865 * errno is set to EINVAL. null is equivalent to 0 (no error values set)
867 * If the value is too big to fit in a double, then the value is set to
868 * the closest infinity with errno set to ERANGE. If strings cannot be
869 * converted to their double value, then EINVAL is set & NaN is returned.
871 * Arrays of length 0 are interpreted as 0 (with no error flags set).
872 * Arrays of length 1 are effectively cast to the equivalent object and
873 * converted using the above rules. All other arrays set the error to
874 * EINVAL & return NaN.
876 * NOTE: Set errno to 0 directly before a call to this function to
877 * determine whether or not conversion was successful (it does not clear
878 * the value for you).
880 * @param obj the json_object instance
881 * @returns a double floating point number
883 JSON_EXPORT double json_object_get_double(const struct json_object *obj);
886 /** Set the double value of a json_object
888 * The type of obj is checked to be a json_type_double and 0 is returned
889 * if it is not without any further actions. If type of obj is json_type_double
890 * the obect value is chaned to new_value
892 * @param obj the json_object instance
893 * @param new_value the value to be set
894 * @returns 1 if value is set correctly, 0 otherwise
896 JSON_EXPORT int json_object_set_double(struct json_object *obj,double new_value);
900 /* string type methods */
902 /** Create a new empty json_object of type json_type_string
904 * A copy of the string is made and the memory is managed by the json_object
906 * @param s the string
907 * @returns a json_object of type json_type_string
909 JSON_EXPORT struct json_object* json_object_new_string(const char *s);
911 JSON_EXPORT struct json_object* json_object_new_string_len(const char *s, int len);
913 /** Get the string value of a json_object
915 * If the passed object is of type json_type_null (i.e. obj == NULL),
918 * If the passed object of type json_type_string, the string contents
921 * Otherwise the JSON representation of the object is returned.
923 * The returned string memory is managed by the json_object and will
924 * be freed when the reference count of the json_object drops to zero.
926 * @param obj the json_object instance
927 * @returns a string or NULL
929 JSON_EXPORT const char* json_object_get_string(struct json_object *obj);
931 /** Get the string length of a json_object
933 * If the passed object is not of type json_type_string then zero
936 * @param obj the json_object instance
939 JSON_EXPORT int json_object_get_string_len(const struct json_object *obj);
942 /** Set the string value of a json_object with zero terminated strings
943 * equivalent to json_object_set_string_len (obj, new_value, strlen(new_value))
944 * @returns 1 if value is set correctly, 0 otherwise
946 JSON_EXPORT int json_object_set_string(json_object* obj, const char* new_value);
948 /** Set the string value of a json_object str
950 * The type of obj is checked to be a json_type_string and 0 is returned
951 * if it is not without any further actions. If type of obj is json_type_string
952 * the obect value is chaned to new_value
954 * @param obj the json_object instance
955 * @param new_value the value to be set; Since string legth is given in len this need not be zero terminated
956 * @param len the length of new_value
957 * @returns 1 if value is set correctly, 0 otherwise
959 JSON_EXPORT int json_object_set_string_len(json_object* obj, const char* new_value, int len);
961 /** Check if two json_object's are equal
963 * If the passed objects are equal 1 will be returned.
964 * Equality is defined as follows:
965 * - json_objects of different types are never equal
966 * - json_objects of the same primitive type are equal if the
967 * c-representation of their value is equal
968 * - json-arrays are considered equal if all values at the same
969 * indices are equal (same order)
970 * - Complex json_objects are considered equal if all
971 * contained objects referenced by their key are equal,
972 * regardless their order.
974 * @param obj1 the first json_object instance
975 * @param obj2 the second json_object instance
976 * @returns whether both objects are equal or not
978 JSON_EXPORT int json_object_equal(struct json_object *obj1,
979 struct json_object *obj2);
982 * Perform a shallow copy of src into *dst as part of an overall json_object_deep_copy().
984 * If src is part of a containing object or array, parent will be non-NULL,
985 * and key or index will be provided.
986 * When shallow_copy is called *dst will be NULL, and must be non-NULL when it returns.
987 * src will never be NULL.
989 * If shallow_copy sets the serializer on an object, return 2 to indicate to
990 * json_object_deep_copy that it should not attempt to use the standard userdata
993 * @return On success 1 or 2, -1 on errors
995 typedef int (json_c_shallow_copy_fn)(json_object *src, json_object *parent, const char *key, size_t index, json_object **dst);
998 * The default shallow copy implementation for use with json_object_deep_copy().
999 * This simply calls the appropriate json_object_new_<type>() function and
1000 * copies over the serializer function (_to_json_string internal field of
1001 * the json_object structure) but not any _userdata or _user_delete values.
1003 * If you're writing a custom shallow_copy function, perhaps because you're using
1004 * your own custom serializer, you can call this first to create the new object
1005 * before customizing it with json_object_set_serializer().
1007 * @return 1 on success, -1 on errors, but never 2.
1009 json_c_shallow_copy_fn json_c_shallow_copy_default;
1012 * Copy the contents of the JSON object.
1013 * The destination object must be initialized to NULL,
1014 * to make sure this function won't overwrite an existing JSON object.
1016 * This does roughly the same thing as
1017 * `json_tokener_parse(json_object_get_string(src))`.
1019 * @param src source JSON object whose contents will be copied
1020 * @param dst pointer to the destination object where the contents of `src`;
1021 * make sure this pointer is initialized to NULL
1022 * @param shallow_copy an optional function to copy individual objects, needed
1023 * when custom serializers are in use. See also
1024 * json_object set_serializer.
1026 * @returns 0 if the copy went well, -1 if an error occured during copy
1027 * or if the destination pointer is non-NULL
1030 JSON_EXPORT int json_object_deep_copy(struct json_object *src, struct json_object **dst, json_c_shallow_copy_fn *shallow_copy);