]> git.ipfire.org Git - thirdparty/json-c.git/blobdiff - json_pointer.h
Merge pull request #861 from bhaible/handle-another-oom-condition
[thirdparty/json-c.git] / json_pointer.h
index 49e9c2985e86825d25f9b90992a4354f7bb26491..dfe1185474e93ad8ef02275b0e4bbbd9aceb458c 100644 (file)
@@ -6,6 +6,11 @@
  *
  */
 
+/**
+ * @file
+ * @brief JSON Pointer (RFC 6901) implementation for retrieving
+ *        objects from a json-c object tree.
+ */
 #ifndef _json_pointer_h_
 #define _json_pointer_h_
 
@@ -27,37 +32,36 @@ extern "C" {
  * Internally, this is equivalent to doing a series of 'json_object_object_get()'
  * and 'json_object_array_get_idx()' along the given 'path'.
  *
- * Note that the 'path' string supports 'printf()' type arguments, so, whatever
- * is added after the 'res' param will be treated as an argument for 'path'
- * Example: json_pointer_get(obj, "/foo/%d/%s", &res, 0, bar)
- * This means, that you need to escape '%' with '%%' (just like in printf())
- *
  * @param obj the json_object instance/tree from where to retrieve sub-objects
  * @param path a (RFC6901) string notation for the sub-object to retrieve
- * @param res a pointer where to store a reference to the json_object
+ * @param res a pointer that stores a reference to the json_object
  *              associated with the given path
  *
  * @return negative if an error (or not found), or 0 if succeeded
  */
-int json_pointer_get(struct json_object *obj, const char *path, struct json_object **res);
+JSON_EXPORT int json_pointer_get(struct json_object *obj, const char *path,
+                                 struct json_object **res);
 
 /**
  * This is a variant of 'json_pointer_get()' that supports printf() style arguments.
  *
- * Example: json_pointer_getf(obj, res, "/foo/%d/%s", 0, bak)
+ * 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.
  *
  * @param obj the json_object instance/tree to which to add a sub-object
- * @param res a pointer where to store a reference to the json_object
+ * @param res a pointer that stores a reference to the json_object
  *              associated with the given path
  * @param path_fmt a printf() style format for the path
  *
  * @return negative if an error (or not found), or 0 if succeeded
  */
-int json_pointer_getf(struct json_object *obj, struct json_object **res, const char *path_fmt, ...);
+JSON_EXPORT int json_pointer_getf(struct json_object *obj, struct json_object **res,
+                                  const char *path_fmt, ...);
 
 /**
  * Sets JSON object 'value' in the 'obj' tree at the location specified
@@ -77,23 +81,21 @@ int json_pointer_getf(struct json_object *obj, struct json_object **res, const c
  * That also implies that 'json_pointer_set()' does not do any refcount incrementing.
  * (Just that single decrement that was mentioned above).
  *
- * Note that the 'path' string supports 'printf()' type arguments, so, whatever
- * is added after the 'value' param will be treated as an argument for 'path'
- * Example: json_pointer_set(obj, "/foo/%d/%s", value, 0, bak)
- * This means, that you need to escape '%' with '%%' (just like in printf())
- *
  * @param obj the json_object instance/tree to which to add a sub-object
  * @param path a (RFC6901) string notation for the sub-object to set in the tree
  * @param value object to set at path
  *
  * @return negative if an error (or not found), or 0 if succeeded
  */
-int json_pointer_set(struct json_object **obj, const char *path, struct json_object *value);
+JSON_EXPORT int json_pointer_set(struct json_object **obj, const char *path,
+                                 struct json_object *value);
 
 /**
  * This is a variant of 'json_pointer_set()' that supports printf() style arguments.
  *
- * Example: json_pointer_setf(obj, value, "/foo/%d/%s", 0, bak)
+ * 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
@@ -105,8 +107,8 @@ int json_pointer_set(struct json_object **obj, const char *path, struct json_obj
  *
  * @return negative if an error (or not found), or 0 if succeeded
  */
-int json_pointer_setf(struct json_object **obj, struct json_object *value, const char *path_fmt, ...);
-
+JSON_EXPORT int json_pointer_setf(struct json_object **obj, struct json_object *value,
+                                  const char *path_fmt, ...);
 
 #ifdef __cplusplus
 }