json_pointer.h File Reference

JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree. More...

## Functions

JSON_EXPORT int | json_pointer_get (struct json_object *obj, const char *path, struct json_object **res)
JSON_EXPORT int | json_pointer_getf (struct json_object *obj, struct json_object **res, const char *path_fmt,...)
JSON_EXPORT int | json_pointer_set (struct json_object **obj, const char *path, struct json_object *value)
JSON_EXPORT int | json_pointer_setf (struct json_object **obj, struct json_object *value, const char *path_fmt,...)

## Detailed Description

JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree.

## Function Documentation

## json_pointer_get()

JSON_EXPORT int json_pointer_get | ( | struct json_object * | obj,
|  | const char * | path,
|  | struct json_object ** | res )

Retrieves a JSON sub-object from inside another JSON object using the JSON pointer notation as defined in RFC 6901 https://tools.ietf.org/html/rfc6901

The returned JSON sub-object is equivalent to parsing manually the 'obj' JSON tree ; i.e. it's not a new object that is created, but rather a pointer inside the JSON tree.

Internally, this is equivalent to doing a series of 'json_object_object_get()' and 'json_object_array_get_idx()' along the given 'path'.

Parameters

  obj | the json_object instance/tree from where to retrieve sub-objects
  path | a (RFC6901) string notation for the sub-object to retrieve
  res | a pointer that stores a reference to the json_object associated with the given path

Returns
  negative if an error (or not found), or 0 if succeeded

References JSON_EXPORT.

## json_pointer_getf()

JSON_EXPORT int json_pointer_getf | ( | struct json_object * | obj,
|  | struct json_object ** | res,
|  | const char * | path_fmt,
|  |  | ... )

This is a variant of 'json_pointer_get()' that supports printf() style arguments.

Variable arguments go after the 'path_fmt' parameter.

Example: json_pointer_getf(obj, res, "/foo/%d/%s", 0, "bar") This also means that you need to escape '' with '%' (just like in printf())

Please take into consideration all recommended 'printf()' format security aspects when using this function.

Parameters

  obj | the json_object instance/tree to which to add a sub-object
  res | a pointer that stores a reference to the json_object associated with the given path
  path_fmt | a printf() style format for the path

Returns
  negative if an error (or not found), or 0 if succeeded

References JSON_EXPORT.

## json_pointer_set()

JSON_EXPORT int json_pointer_set | ( | struct json_object ** | obj,
|  | const char * | path,
|  | struct json_object * | value )

Sets JSON object 'value' in the 'obj' tree at the location specified by the 'path'. 'path' is JSON pointer notation as defined in RFC 6901 https://tools.ietf.org/html/rfc6901

Note that 'obj' is a double pointer, mostly for the "" (empty string) case, where the entire JSON object would be replaced by 'value'. In the case of the "" path, the object at '*obj' will have it's refcount decremented with 'json_object_put()' and the 'value' object will be assigned to it.

For other cases (JSON sub-objects) ownership of 'value' will be transferred into '*obj' via 'json_object_object_add()' & 'json_object_array_put_idx()', so the only time the refcount should be decremented for 'value' is when the return value of 'json_pointer_set()' is negative (meaning the 'value' object did not get set into '*obj').

That also implies that 'json_pointer_set()' does not do any refcount incrementing. (Just that single decrement that was mentioned above).

Parameters

  obj | the json_object instance/tree to which to add a sub-object
  path | a (RFC6901) string notation for the sub-object to set in the tree
  value | object to set at path

Returns
  negative if an error (or not found), or 0 if succeeded

References JSON_EXPORT.

## json_pointer_setf()

JSON_EXPORT int json_pointer_setf | ( | struct json_object ** | obj,
|  | struct json_object * | value,
|  | const char * | path_fmt,
|  |  | ... )

This is a variant of 'json_pointer_set()' that supports printf() style arguments.

Variable arguments go after the 'path_fmt' parameter.

Example: json_pointer_setf(obj, value, "/foo/%d/%s", 0, "bar") This also means that you need to escape '' with '%' (just like in printf())

Please take into consideration all recommended 'printf()' format security aspects when using this function.

Parameters

  obj | the json_object instance/tree to which to add a sub-object
  value | object to set at path
  path_fmt | a printf() style format for the path

Returns
  negative if an error (or not found), or 0 if succeeded

References JSON_EXPORT.