json-c: json_object.h File Reference

json-c 0.12

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
json_object.h File Reference

## Data Structures
struct | json_object_iter

## Macros
#define | THIS_FUNCTION_IS_DEPRECATED(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_NOZERO (1<<2)
#define | FALSE ((json_bool)0)
#define | TRUE ((json_bool)1)
#define | json_object_object_foreach(obj, key, val)
#define | json_object_object_foreachC(obj, iter) 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)

## Typedefs
typedef int | json_bool
typedef struct printbuf | printbuf
typedef struct lh_table | lh_table
typedef struct array_list | array_list
typedef struct json_object | json_object
typedef struct json_object_iter | json_object_iter
typedef struct json_tokener | json_tokener
typedef void( | json_object_delete_fn )(struct json_object *jso, void *userdata)
typedef int( | json_object_to_json_string_fn )(struct json_object *jso, struct printbuf *pb, int level, int flags)
typedef enum json_type | json_type

## Enumerations
enum | json_type { json_type_null, json_type_boolean, json_type_double, json_type_int, json_type_object, json_type_array, json_type_string }

## Functions
struct json_object * | json_object_get (struct json_object *obj)
int | json_object_put (struct json_object *obj)
int | json_object_is_type (struct json_object *obj, enum json_type type)
enum json_type | json_object_get_type (struct json_object *obj)
const char * | json_object_to_json_string (struct json_object *obj)
const char * | json_object_to_json_string_ext (struct json_object *obj, int flags)
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)
struct json_object * | json_object_new_object (void)
struct lh_table * | json_object_get_object (struct json_object *obj)
int | json_object_object_length (struct json_object *obj)
void | json_object_object_add (struct json_object *obj, const char *key, struct json_object *val)
| THIS_FUNCTION_IS_DEPRECATED (extern struct json_object *json_object_object_get(struct json_object *obj, const char *key))
json_bool | json_object_object_get_ex (struct json_object *obj, const char *key, struct json_object **value)
void | json_object_object_del (struct json_object *obj, const char *key)
struct json_object * | json_object_new_array (void)
struct array_list * | json_object_get_array (struct json_object *obj)
int | json_object_array_length (struct json_object *obj)
void | json_object_array_sort (struct json_object *jso, int(*sort_fn)(const void *, const void *))
int | json_object_array_add (struct json_object *obj, struct json_object *val)
int | json_object_array_put_idx (struct json_object *obj, int idx, struct json_object *val)
struct json_object * | json_object_array_get_idx (struct json_object *obj, int idx)
struct json_object * | json_object_new_boolean (json_bool b)
json_bool | json_object_get_boolean (struct json_object *obj)
struct json_object * | json_object_new_int (int32_t i)
struct json_object * | json_object_new_int64 (int64_t i)
int32_t | json_object_get_int (struct json_object *obj)
int64_t | json_object_get_int64 (struct json_object *obj)
struct json_object * | json_object_new_double (double d)
struct json_object * | json_object_new_double_s (double d, const char *ds)
double | json_object_get_double (struct json_object *obj)
struct json_object * | json_object_new_string (const char *s)
struct json_object * | json_object_new_string_len (const char *s, int len)
const char * | json_object_get_string (struct json_object *obj)
int | json_object_get_string_len (struct json_object *obj)

## Variables
const char * | json_number_chars
const char * | json_hex_chars
json_object_delete_fn | json_object_free_userdata
json_object_to_json_string_fn | json_object_userdata_to_json_string

## Macro Definition Documentation

#define FALSE ((json_bool)0)

#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 http://jsonformatter.curiousconcept.com/ for an example of the format.

#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;\
struct json_object *val; \
struct lh_entry *entry ## key; \
struct lh_entry *entry_next ## key = NULL; \
for(entry ## key = json_object_get_object(obj)->head; \
(entry ## key ? ( \
key = (char*)entry ## key->k, \
val = (struct json_object*)entry ## key->v, \
entry_next ## key = entry ## key->next, \
entry ## key) : 0); \
entry ## key = entry_next ## key)
json_object_get_object
struct lh_table * json_object_get_object(struct json_object *obj)
lh_entry
Definition: linkhash.h:62
json_object
Definition: json_object_private.h:21

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
| ) |  | 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)

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

Parameters

  obj | the json_object instance
  iter | the object iterator

#define THIS_FUNCTION_IS_DEPRECATED | ( |  | func | ) | func

#define TRUE ((json_bool)1)

## Typedef Documentation

typedef struct array_list array_list

typedef int json_bool

typedef struct json_object json_object

typedef void( json_object_delete_fn)(struct json_object *jso, void *userdata)

Type of custom user delete functions. See json_object_set_serializer.

typedef struct json_object_iter json_object_iter

typedef int( json_object_to_json_string_fn)(struct json_object *jso, struct printbuf *pb, int level, int flags)

Type of a custom serialization function. See json_object_set_serializer.

typedef struct json_tokener json_tokener

typedef enum json_type json_type

typedef struct lh_table lh_table

typedef struct printbuf printbuf

## Enumeration Type Documentation

enum json_type

Enumerator
json_type_null |
json_type_boolean |
json_type_double |
json_type_int |
json_type_object |
json_type_array |
json_type_string |

## Function Documentation

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

struct json_object* json_object_array_get_idx | ( | struct json_object * | obj,
|  | int | idx
| ) |  |

Get the element at specificed index of the array (a json_object of type json_type_array)

Parameters

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

Returns
  the json_object at the specified index (or NULL)

int json_object_array_length | ( | 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

int json_object_array_put_idx | ( | struct json_object * | obj,
|  | int | 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

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

Parameters

  obj | the json_object instance
  sort_fn | a sorting function

struct json_object* json_object_get | ( | struct json_object * | obj | ) |

Increment the reference count of json_object, thereby grabbing shared ownership of obj.

Parameters

  obj | the json_object instance

struct array_list* json_object_get_array | ( | struct json_object * | obj | ) |

Get the arraylist of a json_object of type json_type_array

Parameters

  obj | the json_object instance

Returns
  an arraylist

json_bool json_object_get_boolean | ( | 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 FALSE if there value is zero or TRUE otherwise. If the passed object is a string it will return TRUE if it has a non zero length. If any other object type is passed TRUE will be returned if the object is not NULL.

Parameters

  obj | the json_object instance

Returns
  a json_bool

double json_object_get_double | ( | 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

int32_t json_object_get_int | ( | 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

int64_t json_object_get_int64 | ( | 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

struct lh_table* json_object_get_object | ( | struct json_object * | obj | ) |

Get the hashtable of a json_object of type json_type_object

Parameters

  obj | the json_object instance

Returns
  a linkhash

const char* json_object_get_string | ( | struct json_object * | obj | ) |

Get the string value of a json_object

If the passed object is not of type json_type_string then 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

int json_object_get_string_len | ( | 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

enum json_type json_object_get_type | ( | 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,

int json_object_is_type | ( | 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,

struct json_object* json_object_new_array | ( | void |  | ) |

Create a new empty json_object of type json_type_array

Returns
  a json_object of type json_type_array

struct json_object* json_object_new_boolean | ( | json_bool | b | ) |

Create a new empty json_object of type json_type_boolean

Parameters

  b | a json_bool TRUE or FALSE (0 or 1)

Returns
  a json_object of type json_type_boolean

struct json_object* json_object_new_double | ( | double | d | ) |

Create a new empty json_object of type json_type_double

Parameters

  d | the double

Returns
  a json_object of type json_type_double

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

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.

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

An equivalent sequence of calls is:

* jso = json_object_new_double(d);
* json_object_set_serializer(d, 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.

struct json_object* json_object_new_int | ( | int32_t | i | ) |

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

struct json_object* json_object_new_int64 | ( | int64_t | i | ) |

Create a new empty json_object of type json_type_int

Parameters

  i | the integer

Returns
  a json_object of type json_type_int

struct json_object* json_object_new_object | ( | void |  | ) |

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

struct json_object* json_object_new_string | ( | const char * | s | ) |

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

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

void 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 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, independent of the lifetime of obj, you must wrap the passed object with json_object_get.

Upon calling this, the ownership of val transfers to obj. Thus you must make sure that you do in fact have ownership over this object. For instance, json_object_new_object will give you ownership until you transfer it, whereas json_object_object_get does not.

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

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_bool json_object_object_get_ex | ( | 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

int json_object_object_length | ( | 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

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.

Parameters

  obj | the json_object instance

Returns
  1 if the object was freed.

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 a custom serializer 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 other parameters are ignored and the default behaviour is reset.

The userdata parameter is optional and may be passed as NULL. If provided, it is passed to to_string_func as-is. 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)

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

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)

Parameters

  obj | the json_object instance

Returns
  a string in JSON format

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

Stringify object to json format

Parameters

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

Returns
  a string in JSON format

THIS_FUNCTION_IS_DEPRECATED | ( | extern struct json_object * | json_object_object_getstruct json_object *obj, const char *key | ) |

Get the json_object associate with a given object field

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

Deprecated:
  Please use json_object_object_get_ex

## Variable Documentation

const char* json_hex_chars

const char* json_number_chars

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_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.