]>
git.ipfire.org Git - thirdparty/json-c.git/blob - json_pointer.h
2 * Copyright (c) 2016 Alexadru Ardelean.
4 * This is free software; you can redistribute it and/or modify
5 * it under the terms of the MIT license. See COPYING for details.
11 * @brief JSON Pointer (RFC 6901) implementation for retrieving
12 * objects from a json-c object tree.
14 #ifndef _json_pointer_h_
15 #define _json_pointer_h_
17 #include "json_object.h"
24 * Retrieves a JSON sub-object from inside another JSON object
25 * using the JSON pointer notation as defined in RFC 6901
26 * https://tools.ietf.org/html/rfc6901
28 * The returned JSON sub-object is equivalent to parsing manually the
29 * 'obj' JSON tree ; i.e. it's not a new object that is created, but rather
30 * a pointer inside the JSON tree.
32 * Internally, this is equivalent to doing a series of 'json_object_object_get()'
33 * and 'json_object_array_get_idx()' along the given 'path'.
35 * @param obj the json_object instance/tree from where to retrieve sub-objects
36 * @param path a (RFC6901) string notation for the sub-object to retrieve
37 * @param res a pointer that stores a reference to the json_object
38 * associated with the given path
40 * @return negative if an error (or not found), or 0 if succeeded
42 JSON_EXPORT
int json_pointer_get(struct json_object
*obj
, const char *path
,
43 struct json_object
**res
);
46 * This is a variant of 'json_pointer_get()' that supports printf() style arguments.
48 * Variable arguments go after the 'path_fmt' parameter.
50 * Example: json_pointer_getf(obj, res, "/foo/%d/%s", 0, "bar")
51 * This also means that you need to escape '%' with '%%' (just like in printf())
53 * Please take into consideration all recommended 'printf()' format security
54 * aspects when using this function.
56 * @param obj the json_object instance/tree to which to add a sub-object
57 * @param res a pointer that stores a reference to the json_object
58 * associated with the given path
59 * @param path_fmt a printf() style format for the path
61 * @return negative if an error (or not found), or 0 if succeeded
63 JSON_EXPORT
int json_pointer_getf(struct json_object
*obj
, struct json_object
**res
,
64 const char *path_fmt
, ...);
67 * Sets JSON object 'value' in the 'obj' tree at the location specified
68 * by the 'path'. 'path' is JSON pointer notation as defined in RFC 6901
69 * https://tools.ietf.org/html/rfc6901
71 * Note that 'obj' is a double pointer, mostly for the "" (empty string)
72 * case, where the entire JSON object would be replaced by 'value'.
73 * In the case of the "" path, the object at '*obj' will have it's refcount
74 * decremented with 'json_object_put()' and the 'value' object will be assigned to it.
76 * For other cases (JSON sub-objects) ownership of 'value' will be transferred into
77 * '*obj' via 'json_object_object_add()' & 'json_object_array_put_idx()', so the
78 * only time the refcount should be decremented for 'value' is when the return value of
79 * 'json_pointer_set()' is negative (meaning the 'value' object did not get set into '*obj').
81 * That also implies that 'json_pointer_set()' does not do any refcount incrementing.
82 * (Just that single decrement that was mentioned above).
84 * @param obj the json_object instance/tree to which to add a sub-object
85 * @param path a (RFC6901) string notation for the sub-object to set in the tree
86 * @param value object to set at path
88 * @return negative if an error (or not found), or 0 if succeeded
90 JSON_EXPORT
int json_pointer_set(struct json_object
**obj
, const char *path
,
91 struct json_object
*value
);
94 * This is a variant of 'json_pointer_set()' that supports printf() style arguments.
96 * Variable arguments go after the 'path_fmt' parameter.
98 * Example: json_pointer_setf(obj, value, "/foo/%d/%s", 0, "bar")
99 * This also means that you need to escape '%' with '%%' (just like in printf())
101 * Please take into consideration all recommended 'printf()' format security
102 * aspects when using this function.
104 * @param obj the json_object instance/tree to which to add a sub-object
105 * @param value object to set at path
106 * @param path_fmt a printf() style format for the path
108 * @return negative if an error (or not found), or 0 if succeeded
110 JSON_EXPORT
int json_pointer_setf(struct json_object
**obj
, struct json_object
*value
,
111 const char *path_fmt
, ...);