json_pointer.h

   1 /*
   2  * Copyright (c) 2016 Alexadru Ardelean.
   3  *
   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.
   6  *
   7  */
   8
   9 /**
  10  * @file
  11  * @brief JSON Pointer (RFC 6901) implementation for retrieving
  12  *        objects from a json-c object tree.
  13  */
  14 #ifndef _json_pointer_h_
  15 #define _json_pointer_h_
  16
  17 #include "json_object.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /**
  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
  27  *
  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.
  31  *
  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'.
  34  *
  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
  39  *
  40  * @return negative if an error (or not found), or 0 if succeeded
  41  */
  42 JSON_EXPORT int json_pointer_get(struct json_object *obj, const char *path,
  43                                  struct json_object **res);
  44
  45 /**
  46  * This is a variant of 'json_pointer_get()' that supports printf() style arguments.
  47  *
  48  * Variable arguments go after the 'path_fmt' parameter.
  49  *
  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())
  52  *
  53  * Please take into consideration all recommended 'printf()' format security
  54  * aspects when using this function.
  55  *
  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
  60  *
  61  * @return negative if an error (or not found), or 0 if succeeded
  62  */
  63 JSON_EXPORT int json_pointer_getf(struct json_object *obj, struct json_object **res,
  64                                   const char *path_fmt, ...);
  65
  66 /**
  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
  70  *
  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.
  75  *
  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').
  80  *
  81  * That also implies that 'json_pointer_set()' does not do any refcount incrementing.
  82  * (Just that single decrement that was mentioned above).
  83  *
  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
  87  *
  88  * @return negative if an error (or not found), or 0 if succeeded
  89  */
  90 JSON_EXPORT int json_pointer_set(struct json_object **obj, const char *path,
  91                                  struct json_object *value);
  92
  93 /**
  94  * This is a variant of 'json_pointer_set()' that supports printf() style arguments.
  95  *
  96  * Variable arguments go after the 'path_fmt' parameter.
  97  *
  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())
 100  *
 101  * Please take into consideration all recommended 'printf()' format security
 102  * aspects when using this function.
 103  *
 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
 107  *
 108  * @return negative if an error (or not found), or 0 if succeeded
 109  */
 110 JSON_EXPORT int json_pointer_setf(struct json_object **obj, struct json_object *value,
 111                                   const char *path_fmt, ...);
 112
 113 #ifdef __cplusplus
 114 }
 115 #endif
 116
 117 #endif