Core json-c API. Start here, or with json_tokener.h. More...

Macros
#define	JSON_C_CONST_FUNCTION(func) func

#define	JSON_OBJECT_DEF_HASH_ENTRIES 16

#define	JSON_C_TO_STRING_PLAIN 0

#define	JSON_C_TO_STRING_SPACED (1 << 0)

#define	JSON_C_TO_STRING_PRETTY (1 << 1)

#define	JSON_C_TO_STRING_PRETTY_TAB (1 << 3)

#define	JSON_C_TO_STRING_NOZERO (1 << 2)

#define	JSON_C_TO_STRING_NOSLASHESCAPE (1 << 4)

#define	JSON_C_TO_STRING_COLOR (1 << 5)

#define	JSON_C_OBJECT_ADD_KEY_IS_NEW (1 << 1)

#define	JSON_C_OBJECT_ADD_CONSTANT_KEY (1 << 2)

#define	JSON_C_OBJECT_KEY_IS_CONSTANT JSON_C_OBJECT_ADD_CONSTANT_KEY

#define	JSON_C_OPTION_GLOBAL (0)

#define	JSON_C_OPTION_THREAD (1)

#define	json_object_object_foreach(obj, key, val)

#define	json_object_object_foreachC(obj, iter)

Typedefs
typedef int(	json_c_shallow_copy_fn )(json_object src, json_object parent, const char key, size_t index, json_object *dst)

Functions
JSON_EXPORT struct json_object *	json_object_get (struct json_object *obj)

JSON_EXPORT int	json_object_put (struct json_object *obj)

JSON_EXPORT int	json_object_is_type (const struct json_object *obj, enum json_type type)

JSON_EXPORT enum json_type	json_object_get_type (const struct json_object *obj)

JSON_EXPORT const char *	json_object_to_json_string (struct json_object *obj)

JSON_EXPORT const char *	json_object_to_json_string_ext (struct json_object *obj, int flags)

JSON_EXPORT const char *	json_object_to_json_string_length (struct json_object obj, int flags, size_t length)

JSON_EXPORT void *	json_object_get_userdata (json_object *jso)

JSON_EXPORT void	json_object_set_userdata (json_object jso, void userdata, json_object_delete_fn *user_delete)

JSON_EXPORT void	json_object_set_serializer (json_object jso, json_object_to_json_string_fn to_string_func, void userdata, json_object_delete_fn user_delete)

JSON_EXPORT struct json_object *	json_object_new_object (void)

JSON_EXPORT struct lh_table *	json_object_get_object (const struct json_object *obj)

JSON_EXPORT int	json_object_object_length (const struct json_object *obj)

size_t	json_c_object_sizeof (void)

JSON_EXPORT int	json_object_object_add (struct json_object obj, const char key, struct json_object *val)

JSON_EXPORT int	json_object_object_add_ex (struct json_object obj, const char const key, struct json_object *const val, const unsigned opts)

JSON_EXPORT struct json_object *	json_object_object_get (const struct json_object obj, const char key)

JSON_EXPORT json_bool	json_object_object_get_ex (const struct json_object obj, const char key, struct json_object **value)

JSON_EXPORT void	json_object_object_del (struct json_object obj, const char key)

JSON_EXPORT struct json_object *	json_object_new_array (void)

JSON_EXPORT struct json_object *	json_object_new_array_ext (int initial_size)

JSON_EXPORT struct array_list *	json_object_get_array (const struct json_object *obj)

JSON_EXPORT size_t	json_object_array_length (const struct json_object *obj)

JSON_EXPORT void	json_object_array_sort (struct json_object jso, int(sort_fn)(const void , const void ))

JSON_EXPORT struct json_object *	json_object_array_bsearch (const struct json_object key, const struct json_object jso, int(sort_fn)(const void , const void *))

JSON_EXPORT int	json_object_array_add (struct json_object obj, struct json_object val)

JSON_EXPORT int	json_object_array_put_idx (struct json_object obj, size_t idx, struct json_object val)

JSON_EXPORT int	json_object_array_insert_idx (struct json_object obj, size_t idx, struct json_object val)

JSON_EXPORT struct json_object *	json_object_array_get_idx (const struct json_object *obj, size_t idx)

JSON_EXPORT int	json_object_array_del_idx (struct json_object *obj, size_t idx, size_t count)

JSON_EXPORT int	json_object_array_shrink (struct json_object *jso, int empty_slots)

JSON_EXPORT struct json_object *	json_object_new_boolean (json_bool b)

JSON_EXPORT json_bool	json_object_get_boolean (const struct json_object *obj)

JSON_EXPORT int	json_object_set_boolean (struct json_object *obj, json_bool new_value)

JSON_EXPORT struct json_object *	json_object_new_int (int32_t i)

JSON_EXPORT struct json_object *	json_object_new_int64 (int64_t i)

JSON_EXPORT struct json_object *	json_object_new_uint64 (uint64_t i)

JSON_EXPORT int32_t	json_object_get_int (const struct json_object *obj)

JSON_EXPORT int	json_object_set_int (struct json_object *obj, int new_value)

JSON_EXPORT int	json_object_int_inc (struct json_object *obj, int64_t val)

JSON_EXPORT int64_t	json_object_get_int64 (const struct json_object *obj)

JSON_EXPORT uint64_t	json_object_get_uint64 (const struct json_object *obj)

JSON_EXPORT int	json_object_set_int64 (struct json_object *obj, int64_t new_value)

JSON_EXPORT int	json_object_set_uint64 (struct json_object *obj, uint64_t new_value)

JSON_EXPORT struct json_object *	json_object_new_double (double d)

JSON_EXPORT struct json_object *	json_object_new_double_s (double d, const char *ds)

JSON_EXPORT int	json_c_set_serialization_double_format (const char *double_format, int global_or_thread)

JSON_EXPORT int	json_object_double_to_json_string (struct json_object jso, struct printbuf pb, int level, int flags)

JSON_EXPORT double	json_object_get_double (const struct json_object *obj)

JSON_EXPORT int	json_object_set_double (struct json_object *obj, double new_value)

JSON_EXPORT struct json_object *	json_object_new_string (const char *s)

JSON_EXPORT struct json_object *	json_object_new_string_len (const char *s, const int len)

JSON_EXPORT const char *	json_object_get_string (struct json_object *obj)

JSON_EXPORT int	json_object_get_string_len (const struct json_object *obj)

JSON_EXPORT int	json_object_set_string (json_object obj, const char new_value)

JSON_EXPORT int	json_object_set_string_len (json_object obj, const char new_value, int len)

JSON_EXPORT struct json_object *	json_object_new_null (void)

JSON_EXPORT int	json_object_equal (struct json_object obj1, struct json_object obj2)

JSON_EXPORT int	json_object_deep_copy (struct json_object src, struct json_object dst, json_c_shallow_copy_fn shallow_copy)

Variables
JSON_EXPORT json_object_delete_fn	json_object_free_userdata

JSON_EXPORT json_object_to_json_string_fn	json_object_userdata_to_json_string

JSON_EXPORT json_c_shallow_copy_fn	json_c_shallow_copy_default

Detailed Description

Core json-c API. Start here, or with json_tokener.h.

Macro Definition Documentation

#define JSON_C_CONST_FUNCTION ( func ) func

#define JSON_C_OBJECT_ADD_CONSTANT_KEY (1 << 2)

A flag for the json_object_object_add_ex function which flags the key as being constant memory. This means that the key will NOT be copied via strdup(), resulting in a potentially huge performance win (malloc, strdup and free are usually performance hogs). It is acceptable to use this flag for keys in non-constant memory blocks if the caller ensure that the memory holding the key lives longer than the corresponding json object. However, this is somewhat dangerous and should only be done if really justified. The general use-case for this flag is cases where the key is given as a real constant value in the function call, e.g. as in json_object_object_add_ex(obj, "ip", json, JSON_C_OBJECT_ADD_CONSTANT_KEY);

#define JSON_C_OBJECT_ADD_KEY_IS_NEW (1 << 1)

A flag for the json_object_object_add_ex function which causes the value to be added without a check if it already exists. Note: it is the responsibility of the caller to ensure that no key is added multiple times. If this is done, results are unpredictable. While this option is somewhat dangerous, it permits potentially large performance savings in code that knows for sure the key values are unique (e.g. because the code adds a well-known set of constant key values).

#define JSON_C_OBJECT_KEY_IS_CONSTANT JSON_C_OBJECT_ADD_CONSTANT_KEY

This flag is an alias to JSON_C_OBJECT_ADD_CONSTANT_KEY. Historically, this flag was used first and the new name JSON_C_OBJECT_ADD_CONSTANT_KEY was introduced for version 0.16.00 in order to have regular naming. Use of this flag is now legacy.

#define JSON_C_OPTION_GLOBAL (0)

Set the global value of an option, which will apply to all current and future threads that have not set a thread-local value.

See Also: json_c_set_serialization_double_format

#define JSON_C_OPTION_THREAD (1)

Set a thread-local value of an option, overriding the global value. This will fail if json-c is not compiled with threading enabled, and with the __thread specifier (or equivalent) available.

See Also: json_c_set_serialization_double_format

#define JSON_C_TO_STRING_COLOR (1 << 5)

A flag for the json_object_to_json_string_ext() and json_object_to_file_ext() functions which causes the output to be formatted.

Use color for printing json.

#define JSON_C_TO_STRING_NOSLASHESCAPE (1 << 4)

Don't escape forward slashes.

#define JSON_C_TO_STRING_NOZERO (1 << 2)

A flag to drop trailing zero for float values

#define JSON_C_TO_STRING_PLAIN 0

A flag for the json_object_to_json_string_ext() and json_object_to_file_ext() functions which causes the output to have no extra whitespace or formatting applied.

#define JSON_C_TO_STRING_PRETTY (1 << 1)

A flag for the json_object_to_json_string_ext() and json_object_to_file_ext() functions which causes the output to be formatted.

See the "Two Space Tab" option at https://jsonformatter.curiousconcept.com/ for an example of the format.

#define JSON_C_TO_STRING_PRETTY_TAB (1 << 3)

A flag for the json_object_to_json_string_ext() and json_object_to_file_ext() functions which causes the output to be formatted.

Instead of a "Two Space Tab" this gives a single tab character.

#define JSON_C_TO_STRING_SPACED (1 << 0)

A flag for the json_object_to_json_string_ext() and json_object_to_file_ext() functions which causes the output to have minimal whitespace inserted to make things slightly more readable.

#define JSON_OBJECT_DEF_HASH_ENTRIES 16

#define json_object_object_foreach	(	obj,
		key,
		val
	)

Value:

char *key = NULL;                                                      \
        struct json_object *val = NULL;                                        \
        struct lh_entry *entry##key;                                           \
        struct lh_entry *entry_next##key = NULL;                               \
        for (entry##key = lh_table_head(json_object_get_object(obj));          \
             (entry##key ? (key = (char *)lh_entry_k(entry##key),              \
                           val = (struct json_object *)lh_entry_v(entry##key), \
                           entry_next##key = lh_entry_next(entry##key), entry##key)     \
                         : 0);                                                 \
             entry##key = entry_next##key)

Iterate through all keys and values of an object.

Adding keys to the object while iterating is NOT allowed.

Deleting an existing key, or replacing an existing key with a new value IS allowed.

Parameters

obj	the json_object instance
key	the local name for the char* key variable defined in the body
val	the local name for the json_object* object variable defined in the body

#define json_object_object_foreachC	(	obj,
		iter
	)

Value:

for (iter.entry = lh_table_head(json_object_get_object(obj));                                    \
             (iter.entry ? (iter.key = (char *)lh_entry_k(iter.entry),                          \
                           iter.val = (struct json_object *)lh_entry_v(iter.entry), iter.entry) \
                         : 0);                                                                  \
             iter.entry = lh_entry_next(iter.entry))

Iterate through all keys and values of an object (ANSI C Safe)

Parameters

obj	the json_object instance
iter	the object iterator, use type json_object_iter

Typedef Documentation

typedef int( json_c_shallow_copy_fn)(json_object *src, json_object *parent, const char *key, size_t index, json_object **dst)

Perform a shallow copy of src into *dst as part of an overall json_object_deep_copy().

If src is part of a containing object or array, parent will be non-NULL, and key or index will be provided. When shallow_copy is called *dst will be NULL, and must be non-NULL when it returns. src will never be NULL.

If shallow_copy sets the serializer on an object, return 2 to indicate to json_object_deep_copy that it should not attempt to use the standard userdata copy function.

Returns: On success 1 or 2, -1 on errors

Function Documentation

size_t json_c_object_sizeof ( void )

Get the sizeof (struct json_object).

Returns: a size_t with the sizeof (struct json_object)

JSON_EXPORT int json_c_set_serialization_double_format	(	const char *	double_format,
		int	global_or_thread
	)

Set a global or thread-local json-c option, depending on whether JSON_C_OPTION_GLOBAL or JSON_C_OPTION_THREAD is passed. Thread-local options default to undefined, and inherit from the global value, even if the global value is changed after the thread is created. Attempting to set thread-local options when threading is not compiled in will result in an error. Be sure to check the return value.

double_format is a "%g" printf format, such as "%.20g"

Returns: -1 on errors, 0 on success.

JSON_EXPORT int json_object_array_add	(	struct json_object *	obj,
		struct json_object *	val
	)

Add an element to the end of a json_object of type json_type_array

The reference count will not be incremented. This is to make adding fields to objects in code more compact. If you want to retain a reference to an added object you must wrap the passed object with json_object_get

Parameters

obj	the json_object instance
val	the json_object to be added

JSON_EXPORT struct json_object* json_object_array_bsearch	(	const struct json_object *	key,
		const struct json_object *	jso,
		int()(const void , const void *)	sort_fn
	)

read

Binary search a sorted array for a specified key object.

It depends on your compare function what's sufficient as a key. Usually you create some dummy object with the parameter compared in it, to identify the right item you're actually looking for.

See Also: json_object_array_sort() for hints on the compare function.

Parameters

key	a dummy json_object with the right key
jso	the array object we're searching
sort_fn	the sort/compare function

Returns: the wanted json_object instance

JSON_EXPORT int json_object_array_del_idx	(	struct json_object *	obj,
		size_t	idx,
		size_t	count
	)

Delete an elements from a specified index in an array (a json_object of type json_type_array)

The reference count will be decremented for each of the deleted objects. If there are no more owners of an element that is being deleted, then the value is freed. Otherwise, the reference to the value will remain in memory.

Parameters

obj	the json_object instance
idx	the index to start deleting elements at
count	the number of elements to delete

Returns: 0 if the elements were successfully deleted

JSON_EXPORT struct json_object* json_object_array_get_idx	(	const struct json_object *	obj,
		size_t	idx
	)

read

Get the element at specified index of array obj (which must be a json_object of type json_type_array)

No reference counts will be changed, and ownership of the returned object remains with obj. See json_object_object_get() for additional implications of this behavior.

Calling this with anything other than a json_type_array will trigger an assert.

Parameters

obj	the json_object instance
idx	the index to get the element at

Returns: the json_object at the specified index (or NULL)

JSON_EXPORT int json_object_array_insert_idx	(	struct json_object *	obj,
		size_t	idx,
		struct json_object *	val
	)

Insert an element at a specified index in an array (a json_object of type json_type_array)

The reference count will not be incremented. This is to make adding fields to objects in code more compact. If you want to retain a reference to an added object you must wrap the passed object with json_object_get

The array size will be automatically be expanded to the size of the index if the index is larger than the current size. If the index is within the existing array limits, then the element will be inserted and all elements will be shifted. This is the only difference between this function and json_object_array_put_idx().

Parameters

obj	the json_object instance
idx	the index to insert the element at
val	the json_object to be added

JSON_EXPORT size_t json_object_array_length ( const struct json_object * obj )

Get the length of a json_object of type json_type_array

Parameters

obj	the json_object instance

Returns: an int

JSON_EXPORT int json_object_array_put_idx	(	struct json_object *	obj,
		size_t	idx,
		struct json_object *	val
	)

Insert or replace an element at a specified index in an array (a json_object of type json_type_array)

The reference count will not be incremented. This is to make adding fields to objects in code more compact. If you want to retain a reference to an added object you must wrap the passed object with json_object_get

The reference count of a replaced object will be decremented.

The array size will be automatically be expanded to the size of the index if the index is larger than the current size.

Parameters

obj	the json_object instance
idx	the index to insert the element at
val	the json_object to be added

JSON_EXPORT int json_object_array_shrink	(	struct json_object *	jso,
		int	empty_slots
	)

Shrink the internal memory allocation of the array to just enough to fit the number of elements in it, plus empty_slots.

Parameters

jso	the json_object instance, must be json_type_array
empty_slots	the number of empty slots to leave allocated

JSON_EXPORT void json_object_array_sort	(	struct json_object *	jso,
		int()(const void , const void *)	sort_fn
	)

Sorts the elements of jso of type json_type_array

Pointers to the json_object pointers will be passed as the two arguments to sort_fn

Parameters

jso	the json_object instance
sort_fn	a sorting function

JSON_EXPORT int json_object_deep_copy	(	struct json_object *	src,
		struct json_object **	dst,
		json_c_shallow_copy_fn *	shallow_copy
	)

Copy the contents of the JSON object. The destination object must be initialized to NULL, to make sure this function won't overwrite an existing JSON object.

This does roughly the same thing as json_tokener_parse(json_object_get_string(src)).

Parameters

src	source JSON object whose contents will be copied
dst	pointer to the destination object where the contents of `src`; make sure this pointer is initialized to NULL
shallow_copy	an optional function to copy individual objects, needed when custom serializers are in use. See also json_object set_serializer.

Returns: 0 if the copy went well, -1 if an error occurred during copy or if the destination pointer is non-NULL

JSON_EXPORT int json_object_double_to_json_string	(	struct json_object *	jso,
		struct printbuf *	pb,
		int	level,
		int	flags
	)

Serialize a json_object of type json_type_double to a string.

This function isn't meant to be called directly. Instead, you can set a custom format string for the serialization of this double using the following call (where "%.17g" actually is the default):

jso = json_object_new_double(d);
json_object_set_serializer(jso, json_object_double_to_json_string,
    "%.17g", NULL);

See Also: printf(3) man page for format strings

Parameters

jso	The json_type_double object that is serialized.
pb	The destination buffer.
level	Ignored.
flags	Ignored.

JSON_EXPORT int json_object_equal	(	struct json_object *	obj1,
		struct json_object *	obj2
	)

Check if two json_object's are equal

If the passed objects are equal 1 will be returned. Equality is defined as follows:

json_objects of different types are never equal
json_objects of the same primitive type are equal if the c-representation of their value is equal
json-arrays are considered equal if all values at the same indices are equal (same order)
Complex json_objects are considered equal if all contained objects referenced by their key are equal, regardless their order.

Parameters

obj1	the first json_object instance
obj2	the second json_object instance

Returns: whether both objects are equal or not

JSON_EXPORT struct json_object* json_object_get ( struct json_object * obj )

read

Increment the reference count of json_object, thereby taking ownership of it.

Cases where you might need to increase the refcount include:

Using an object field or array index (retrieved through json_object_object_get() or json_object_array_get_idx()) beyond the lifetime of the parent object.
Detaching an object field or array index from its parent object (using json_object_object_del() or json_object_array_del_idx())
Sharing a json_object with multiple (not necessarily parallel) threads of execution that all expect to free it (with json_object_put()) when they're done.

Parameters

obj	the json_object instance

See Also: json_object_put(); json_object_object_get(); json_object_array_get_idx()

JSON_EXPORT struct array_list* json_object_get_array ( const struct json_object * obj )

read

Get the arraylist of a json_object of type json_type_array

Parameters

obj	the json_object instance

Returns: an arraylist

JSON_EXPORT json_bool json_object_get_boolean ( const struct json_object * obj )

Get the json_bool value of a json_object

The type is coerced to a json_bool if the passed object is not a json_bool. integer and double objects will return 0 if there value is zero or 1 otherwise. If the passed object is a string it will return 1 if it has a non zero length. If any other object type is passed 0 will be returned, even non-empty json_type_array and json_type_object objects.

Parameters

obj	the json_object instance

Returns: a json_bool

JSON_EXPORT double json_object_get_double ( const struct json_object * obj )

Get the double floating point value of a json_object

The type is coerced to a double if the passed object is not a double. integer objects will return their double conversion. Strings will be parsed as a double. If no conversion exists then 0.0 is returned and errno is set to EINVAL. null is equivalent to 0 (no error values set)

If the value is too big to fit in a double, then the value is set to the closest infinity with errno set to ERANGE. If strings cannot be converted to their double value, then EINVAL is set & NaN is returned.

Arrays of length 0 are interpreted as 0 (with no error flags set). Arrays of length 1 are effectively cast to the equivalent object and converted using the above rules. All other arrays set the error to EINVAL & return NaN.

NOTE: Set errno to 0 directly before a call to this function to determine whether or not conversion was successful (it does not clear the value for you).

Parameters

obj	the json_object instance

Returns: a double floating point number

JSON_EXPORT int32_t json_object_get_int ( const struct json_object * obj )

Get the int value of a json_object

The type is coerced to a int if the passed object is not a int. double objects will return their integer conversion. Strings will be parsed as an integer. If no conversion exists then 0 is returned and errno is set to EINVAL. null is equivalent to 0 (no error values set)

Note that integers are stored internally as 64-bit values. If the value of too big or too small to fit into 32-bit, INT32_MAX or INT32_MIN are returned, respectively.

Parameters

obj	the json_object instance

Returns: an int

JSON_EXPORT int64_t json_object_get_int64 ( const struct json_object * obj )

Get the int value of a json_object

The type is coerced to a int64 if the passed object is not a int64. double objects will return their int64 conversion. Strings will be parsed as an int64. If no conversion exists then 0 is returned.

NOTE: Set errno to 0 directly before a call to this function to determine whether or not conversion was successful (it does not clear the value for you).

Parameters

obj	the json_object instance

Returns: an int64

JSON_EXPORT struct lh_table* json_object_get_object ( const struct json_object * obj )

read

Get the hashtable of a json_object of type json_type_object

Parameters

obj	the json_object instance

Returns: a linkhash

JSON_EXPORT const char* json_object_get_string ( struct json_object * obj )

Get the string value of a json_object

If the passed object is of type json_type_null (i.e. obj == NULL), NULL is returned.

If the passed object of type json_type_string, the string contents are returned.

Otherwise the JSON representation of the object is returned.

The returned string memory is managed by the json_object and will be freed when the reference count of the json_object drops to zero.

Parameters

obj	the json_object instance

Returns: a string or NULL

JSON_EXPORT int json_object_get_string_len ( const struct json_object * obj )

Get the string length of a json_object

If the passed object is not of type json_type_string then zero will be returned.

Parameters

obj	the json_object instance

Returns: int

JSON_EXPORT enum json_type json_object_get_type ( const struct json_object * obj )

Get the type of the json_object. See also json_type_to_name() to turn this into a string suitable, for instance, for logging.

Parameters

obj	the json_object instance

Returns: type being one of: json_type_null (i.e. obj == NULL), json_type_boolean, json_type_double, json_type_int, json_type_object, json_type_array, json_type_string

JSON_EXPORT uint64_t json_object_get_uint64 ( const struct json_object * obj )

Get the uint value of a json_object

The type is coerced to a uint64 if the passed object is not a uint64. double objects will return their uint64 conversion. Strings will be parsed as an uint64. If no conversion exists then 0 is returned.

NOTE: Set errno to 0 directly before a call to this function to determine whether or not conversion was successful (it does not clear the value for you).

Parameters

obj	the json_object instance

Returns: an uint64

JSON_EXPORT void* json_object_get_userdata ( json_object * jso )

Returns the userdata set by json_object_set_userdata() or json_object_set_serializer()

Parameters

jso	the object to return the userdata for

JSON_EXPORT int json_object_int_inc	(	struct json_object *	obj,
		int64_t	val
	)

Increment a json_type_int object by the given amount, which may be negative.

If the type of obj is not json_type_int then 0 is returned with no further action taken. If the addition would result in a overflow, the object value is set to INT64_MAX. If the addition would result in a underflow, the object value is set to INT64_MIN. Neither overflow nor underflow affect the return value.

Parameters

obj	the json_object instance
val	the value to add

Returns: 1 if the increment succeeded, 0 otherwise

JSON_EXPORT int json_object_is_type	(	const struct json_object *	obj,
		enum json_type	type
	)

Check if the json_object is of a given type

Parameters

obj	the json_object instance
type	one of: json_type_null (i.e. obj == NULL), json_type_boolean, json_type_double, json_type_int, json_type_object, json_type_array, json_type_string

JSON_EXPORT struct json_object* json_object_new_array ( void )

read

Create a new empty json_object of type json_type_array with 32 slots allocated. If you know the array size you'll need ahead of time, use json_object_new_array_ext() instead.

See Also: json_object_new_array_ext(); json_object_array_shrink()

Returns: a json_object of type json_type_array

JSON_EXPORT struct json_object* json_object_new_array_ext ( int initial_size )

read

Create a new empty json_object of type json_type_array with the desired number of slots allocated.

See Also: json_object_array_shrink()

Parameters

initial_size the number of slots to allocate

Returns: a json_object of type json_type_array

JSON_EXPORT struct json_object* json_object_new_boolean ( json_bool b )

read

Create a new empty json_object of type json_type_boolean

Parameters

b	a json_bool 1 or 0

Returns: a json_object of type json_type_boolean

JSON_EXPORT struct json_object* json_object_new_double ( double d )

read

Create a new empty json_object of type json_type_double

See Also: json_object_double_to_json_string() for how to set a custom format string.

Parameters

d	the double

Returns: a json_object of type json_type_double

JSON_EXPORT struct json_object* json_object_new_double_s	(	double	d,
		const char *	ds
	)

read

Create a new json_object of type json_type_double, using the exact serialized representation of the value.

This allows for numbers that would otherwise get displayed inefficiently (e.g. 12.3 => "12.300000000000001") to be serialized with the more convenient form.

Notes:

This is used by json_tokener_parse_ex() to allow for an exact re-serialization of a parsed object.

The userdata field is used to store the string representation, so it can't be used for other data if this function is used.

A roughly equivalent sequence of calls, with the difference being that the serialization function won't be reset by json_object_set_double(), is:

jso = json_object_new_double(d);
json_object_set_serializer(jso, json_object_userdata_to_json_string,
    strdup(ds), json_object_free_userdata);

Parameters

d	the numeric value of the double.
ds	the string representation of the double. This will be copied.

JSON_EXPORT struct json_object* json_object_new_int ( int32_t i )

read

Create a new empty json_object of type json_type_int Note that values are stored as 64-bit values internally. To ensure the full range is maintained, use json_object_new_int64 instead.

Parameters

i	the integer

Returns: a json_object of type json_type_int

JSON_EXPORT struct json_object* json_object_new_int64 ( int64_t i )

read

Create a new empty json_object of type json_type_int

Parameters

i	the integer

Returns: a json_object of type json_type_int

JSON_EXPORT struct json_object* json_object_new_null ( void )

read

This method exists only to provide a complementary function along the lines of the other json_object_new_* functions. It always returns NULL, and it is entirely acceptable to simply use NULL directly.

JSON_EXPORT struct json_object* json_object_new_object ( void )

read

Create a new empty object with a reference count of 1. The caller of this object initially has sole ownership. Remember, when using json_object_object_add or json_object_array_put_idx, ownership will transfer to the object/array. Call json_object_get if you want to maintain shared ownership or also add this object as a child of multiple objects or arrays. Any ownerships you acquired but did not transfer must be released through json_object_put.

Returns: a json_object of type json_type_object

JSON_EXPORT struct json_object* json_object_new_string ( const char * s )

read

Create a new empty json_object of type json_type_string

A copy of the string is made and the memory is managed by the json_object

Parameters

s	the string

Returns: a json_object of type json_type_string

See Also: json_object_new_string_len()

JSON_EXPORT struct json_object* json_object_new_string_len	(	const char *	s,
		const int	len
	)

read

Create a new empty json_object of type json_type_string and allocate len characters for the new string.

A copy of the string is made and the memory is managed by the json_object

Parameters

s	the string
len	max length of the new string

Returns: a json_object of type json_type_string

See Also: json_object_new_string()

JSON_EXPORT struct json_object* json_object_new_uint64 ( uint64_t i )

read

Create a new empty json_object of type json_type_uint

Parameters

i	the integer

Returns: a json_object of type json_type_uint

JSON_EXPORT int json_object_object_add	(	struct json_object *	obj,
		const char *	key,
		struct json_object *	val
	)

Add an object field to a json_object of type json_type_object

The reference count of val will not be incremented, in effect transferring ownership that object to obj, and thus val will be freed when obj is. (i.e. through json_object_put(obj))

If you want to retain a reference to the added object, independent of the lifetime of obj, you must increment the refcount with json_object_get(val) (and later release it with json_object_put()).

Since ownership transfers to obj, you must make sure that you do in fact have ownership over val. For instance, json_object_new_object() will give you ownership until you transfer it, whereas json_object_object_get() does not.

Any previous object stored under key in obj will have its refcount decremented, and be freed normally if that drops to zero.

Parameters

obj	the json_object instance
key	the object field name (a private copy will be duplicated)
val	a json_object or NULL member to associate with the given field

Returns: On success, 0 is returned. On error, a negative value is returned.

JSON_EXPORT int json_object_object_add_ex	(	struct json_object *	obj,
		const char *const	key,
		struct json_object *const	val,
		const unsigned	opts
	)

Add an object field to a json_object of type json_type_object

The semantics are identical to json_object_object_add, except that an additional flag fields gives you more control over some detail aspects of processing. See the description of JSON_C_OBJECT_ADD_* flags for more details.

Parameters

obj	the json_object instance
key	the object field name (a private copy will be duplicated)
val	a json_object or NULL member to associate with the given field
opts	process-modifying options. To specify multiple options, use (OPT1\|OPT2)

JSON_EXPORT void json_object_object_del	(	struct json_object *	obj,
		const char *	key
	)

Delete the given json_object field

The reference count will be decremented for the deleted object. If there are no more owners of the value represented by this key, then the value is freed. Otherwise, the reference to the value will remain in memory.

Parameters

obj	the json_object instance
key	the object field name

JSON_EXPORT struct json_object* json_object_object_get	(	const struct json_object *	obj,
		const char *	key
	)

read

Get the json_object associate with a given object field. Deprecated/discouraged: used json_object_object_get_ex instead.

This returns NULL if the field is found but its value is null, or if the field is not found, or if obj is not a json_type_object. If you need to distinguish between these cases, use json_object_object_get_ex().

No reference counts will be changed. There is no need to manually adjust reference counts through the json_object_put/json_object_get methods unless you need to have the child (value) reference maintain a different lifetime than the owning parent (obj). Ownership of the returned value is retained by obj (do not do json_object_put unless you have done a json_object_get). If you delete the value from obj (json_object_object_del) and wish to access the returned reference afterwards, make sure you have first gotten shared ownership through json_object_get (& don't forget to do a json_object_put or transfer ownership to prevent a memory leak).

Parameters

obj	the json_object instance
key	the object field name

Returns: the json_object associated with the given field name

JSON_EXPORT json_bool json_object_object_get_ex	(	const struct json_object *	obj,
		const char *	key,
		struct json_object **	value
	)

Get the json_object associated with a given object field.

This returns true if the key is found, false in all other cases (including if obj isn't a json_type_object).

No reference counts will be changed. There is no need to manually adjust reference counts through the json_object_put/json_object_get methods unless you need to have the child (value) reference maintain a different lifetime than the owning parent (obj). Ownership of value is retained by obj.

Parameters

obj	the json_object instance
key	the object field name
value	a pointer where to store a reference to the json_object associated with the given field name.

It is safe to pass a NULL value.

Returns: whether or not the key exists

JSON_EXPORT int json_object_object_length ( const struct json_object * obj )

Get the size of an object in terms of the number of fields it has.

Parameters

obj	the json_object whose length to return

JSON_EXPORT int json_object_put ( struct json_object * obj )

Decrement the reference count of json_object and free if it reaches zero.

You must have ownership of obj prior to doing this or you will cause an imbalance in the reference count, leading to a classic use-after-free bug. In particular, you normally do not need to call json_object_put() on the json_object returned by json_object_object_get() or json_object_array_get_idx().

Just like after calling free() on a block of memory, you must not use obj after calling json_object_put() on it or any object that it is a member of (unless you know you've called json_object_get(obj) to explicitly increment the refcount).

NULL may be passed, which which case this is a no-op.

Parameters

obj	the json_object instance

Returns: 1 if the object was freed.

See Also: json_object_get()

JSON_EXPORT int json_object_set_boolean	(	struct json_object *	obj,
		json_bool	new_value
	)

Set the json_bool value of a json_object

The type of obj is checked to be a json_type_boolean and 0 is returned if it is not without any further actions. If type of obj is json_type_boolean the object value is changed to new_value

Parameters

obj	the json_object instance
new_value	the value to be set

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT int json_object_set_double	(	struct json_object *	obj,
		double	new_value
	)

Set the double value of a json_object

The type of obj is checked to be a json_type_double and 0 is returned if it is not without any further actions. If type of obj is json_type_double the object value is changed to new_value

If the object was created with json_object_new_double_s(), the serialization function is reset to the default and the cached serialized value is cleared.

Parameters

obj	the json_object instance
new_value	the value to be set

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT int json_object_set_int	(	struct json_object *	obj,
		int	new_value
	)

Set the int value of a json_object

The type of obj is checked to be a json_type_int and 0 is returned if it is not without any further actions. If type of obj is json_type_int the object value is changed to new_value

Parameters

obj	the json_object instance
new_value	the value to be set

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT int json_object_set_int64	(	struct json_object *	obj,
		int64_t	new_value
	)

Set the int64_t value of a json_object

The type of obj is checked to be a json_type_int and 0 is returned if it is not without any further actions. If type of obj is json_type_int the object value is changed to new_value

Parameters

obj	the json_object instance
new_value	the value to be set

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT void json_object_set_serializer	(	json_object *	jso,
		json_object_to_json_string_fn *	to_string_func,
		void *	userdata,
		json_object_delete_fn *	user_delete
	)

Set a custom serialization function to be used when this particular object is converted to a string by json_object_to_json_string.

If custom userdata is already set on this object, any existing user_delete function is called before the new one is set.

If to_string_func is NULL the default behaviour is reset (but the userdata and user_delete fields are still set).

The userdata parameter is optional and may be passed as NULL. It can be used to provide additional data for to_string_func to use. This parameter may be NULL even if user_delete is non-NULL.

The user_delete parameter is optional and may be passed as NULL, even if the userdata parameter is non-NULL. It will be called just before the json_object is deleted, after it's reference count goes to zero (see json_object_put()). If this is not provided, it is up to the caller to free the userdata at an appropriate time. (i.e. after the json_object is deleted)

Note that the userdata is the same as set by json_object_set_userdata(), so care must be taken not to overwrite the value when both a custom serializer and json_object_set_userdata() are used.

Parameters

jso	the object to customize
to_string_func	the custom serialization function
userdata	an optional opaque cookie
user_delete	an optional function from freeing userdata

JSON_EXPORT int json_object_set_string	(	json_object *	obj,
		const char *	new_value
	)

Set the string value of a json_object with zero terminated strings equivalent to json_object_set_string_len (obj, new_value, strlen(new_value))

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT int json_object_set_string_len	(	json_object *	obj,
		const char *	new_value,
		int	len
	)

Set the string value of a json_object str

The type of obj is checked to be a json_type_string and 0 is returned if it is not without any further actions. If type of obj is json_type_string the object value is changed to new_value

Parameters

obj	the json_object instance
new_value	the value to be set; Since string length is given in len this need not be zero terminated
len	the length of new_value

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT int json_object_set_uint64	(	struct json_object *	obj,
		uint64_t	new_value
	)

Set the uint64_t value of a json_object

The type of obj is checked to be a json_type_uint and 0 is returned if it is not without any further actions. If type of obj is json_type_uint the object value is changed to new_value

Parameters

obj	the json_object instance
new_value	the value to be set

Returns: 1 if value is set correctly, 0 otherwise

JSON_EXPORT void json_object_set_userdata	(	json_object *	jso,
		void *	userdata,
		json_object_delete_fn *	user_delete
	)

Set an opaque userdata value for an object

The userdata can be retrieved using json_object_get_userdata().

If custom userdata is already set on this object, any existing user_delete function is called before the new one is set.

The user_delete parameter is optional and may be passed as NULL, even if the userdata parameter is non-NULL. It will be called just before the json_object is deleted, after it's reference count goes to zero (see json_object_put()). If this is not provided, it is up to the caller to free the userdata at an appropriate time. (i.e. after the json_object is deleted)

Note: Objects created by parsing strings may have custom serializers set which expect the userdata to contain specific data (due to use of json_object_new_double_s()). In this case, json_object_set_serialiser() with NULL as to_string_func should be used instead to set the userdata and reset the serializer to its default value.

Parameters

jso	the object to set the userdata for
userdata	an optional opaque cookie
user_delete	an optional function from freeing userdata

JSON_EXPORT const char* json_object_to_json_string ( struct json_object * obj )

Stringify object to json format. Equivalent to json_object_to_json_string_ext(obj, JSON_C_TO_STRING_SPACED) The pointer you get is an internal of your json object. You don't have to free it, later use of json_object_put() should be sufficient. If you can not ensure there's no concurrent access to *obj use strdup().

Parameters

obj	the json_object instance

Returns: a string in JSON format

JSON_EXPORT const char* json_object_to_json_string_ext	(	struct json_object *	obj,
		int	flags
	)

Stringify object to json format

See Also: json_object_to_json_string() for details on how to free string.

Parameters

obj	the json_object instance
flags	formatting options, see JSON_C_TO_STRING_PRETTY and other constants

Returns: a string in JSON format

JSON_EXPORT const char* json_object_to_json_string_length	(	struct json_object *	obj,
		int	flags,
		size_t *	length
	)

Stringify object to json format

See Also: json_object_to_json_string() for details on how to free string.

Parameters

obj	the json_object instance
flags	formatting options, see JSON_C_TO_STRING_PRETTY and other constants
length	a pointer where, if not NULL, the length (without null) is stored

Returns: a string in JSON format and the length if not NULL

Variable Documentation

JSON_EXPORT json_c_shallow_copy_fn json_c_shallow_copy_default

The default shallow copy implementation for use with json_object_deep_copy(). This simply calls the appropriate json_object_new_<type>() function and copies over the serializer function (_to_json_string internal field of the json_object structure) but not any _userdata or _user_delete values.

If you're writing a custom shallow_copy function, perhaps because you're using your own custom serializer, you can call this first to create the new object before customizing it with json_object_set_serializer().

Returns: 1 on success, -1 on errors, but never 2.

JSON_EXPORT json_object_delete_fn json_object_free_userdata

Simply call free on the userdata pointer. Can be used with json_object_set_serializer().

Parameters

jso	unused
userdata	the pointer that is passed to free().

JSON_EXPORT json_object_to_json_string_fn json_object_userdata_to_json_string

Copy the jso->_userdata string over to pb as-is. Can be used with json_object_set_serializer().

Parameters

jso	The object whose _userdata is used.
pb	The destination buffer.
level	Ignored.
flags	Ignored.

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation