json_pointer.h File Reference

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

Typedefs
typedef int(*	json_pointer_set_cb) (json_object *parent, const char *key, size_t idx, json_object *value, void *priv)

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,...)
JSON_EXPORT int	json_pointer_set_with_limit_index (struct json_object **obj, const char *path, struct json_object *value, size_t limit_index)
JSON_EXPORT int	json_pointer_set_with_cb (struct json_object **obj, const char *path, struct json_object *value, json_pointer_set_cb set_cb, int cb_handles_obj, void *priv)
JSON_EXPORT int	json_object_array_put_with_idx_limit_cb (struct json_object *jso, const char *key, size_t idx, struct json_object *jso_new, void *priv)

Detailed Description

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

Typedef Documentation

json_pointer_set_cb

typedef int(* json_pointer_set_cb) (json_object *parent, const char *key, size_t idx, json_object *value, void *priv)

Callback function type.

When setting an array element, 'key' will be NULL and 'idx' will be the target index. When setting an object field, 'key' will be the target key and 'idx' will be -1.

Function Documentation

json_object_array_put_with_idx_limit_cb()

JSON_EXPORT int json_object_array_put_with_idx_limit_cb	(	struct json_object *	jso,
		const char *	key,
		size_t	idx,
		struct json_object *	jso_new,
		void *	priv
	)

A safer callback for 'json_pointer_set_with_cb()' that enforces a maximum array index.

This function can be used as the 'set_cb' argument to prevent OOM. It expects the 'priv' argument to be a valid pointer to a 'size_t' variable that holds the maximum allowed index.

Parameters

jso	the parent json_object array.
key	the object field where the element is to be placed, should be NULL here.
idx	the index where the element is to be placed.
jso_new	the new json_object to place at the index.
priv	A pointer to a 'size_t' variable specifying the maximum index. This pointer must not be NULL.

Returns

0 on success, or a negative value if idx exceeds the limit or 'priv' is NULL.

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

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

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

Warning

This function is vulnerable to an OOM. To prevent this, use the safer variant 'json_pointer_set_with_limit_index()' or the flexible 'json_pointer_set_with_array_cb()' with a custom callback.

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

json_pointer_set_with_cb()

JSON_EXPORT int json_pointer_set_with_cb	(	struct json_object **	obj,
		const char *	path,
		struct json_object *	value,
		json_pointer_set_cb	set_cb,
		int	cb_handles_obj,
		void *	priv
	)

Variant of 'json_pointer_set()' that allows specifying a custom callback

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
set_cb	A custom callback function to handle setting the element
cb_handles_obj	If 0, the callback is only invoked for array modifications. If 1, the callback is invoked for both array and object modifications.
priv	A private pointer passed through to the set_cb callback, for user-defined context

Returns

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

json_pointer_set_with_limit_index()

JSON_EXPORT int json_pointer_set_with_limit_index	(	struct json_object **	obj,
		const char *	path,
		struct json_object *	value,
		size_t	limit_index
	)

A convenient and safe variant of 'json_pointer_set()' that prevents excessive memory allocations by enforcing a limit on array indices.

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
limit_index	The maximum allowed value for an array index. If a path contains an index larger than this, the function will fail with errno set to EINVAL. A value of -1 can be used to specify no limit, reverting to the original behavior

Returns

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

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