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  * Note that the 'path' string supports 'printf()' type arguments, so, whatever
  36  * is added after the 'res' param will be treated as an argument for 'path'
  37  * Example: json_pointer_get(obj, "/foo/%d/%s", &res, 0, bar)
  38  * This means, that you need to escape '%' with '%%' (just like in printf())
  39  *
  40  * @param obj the json_object instance/tree from where to retrieve sub-objects
  41  * @param path a (RFC6901) string notation for the sub-object to retrieve
  42  * @param res a pointer that stores a reference to the json_object
  43  *              associated with the given path
  44  *
  45  * @return negative if an error (or not found), or 0 if succeeded
  46  */
  47 int json_pointer_get(struct json_object *obj, const char *path, struct json_object **res);
  48
  49 /**
  50  * This is a variant of 'json_pointer_get()' that supports printf() style arguments.
  51  *
  52  * Example: json_pointer_getf(obj, res, "/foo/%d/%s", 0, bak)
  53  * This also means that you need to escape '%' with '%%' (just like in printf())
  54  *
  55  * Please take into consideration all recommended 'printf()' format security
  56  * aspects when using this function.
  57  *
  58  * @param obj the json_object instance/tree to which to add a sub-object
  59  * @param res a pointer that stores a reference to the json_object
  60  *              associated with the given path
  61  * @param path_fmt a printf() style format for the path
  62  *
  63  * @return negative if an error (or not found), or 0 if succeeded
  64  */
  65 int json_pointer_getf(struct json_object *obj, struct json_object **res, const char *path_fmt, ...);
  66
  67 /**
  68  * Sets JSON object 'value' in the 'obj' tree at the location specified
  69  * by the 'path'. 'path' is JSON pointer notation as defined in RFC 6901
  70  *   https://tools.ietf.org/html/rfc6901
  71  *
  72  * Note that 'obj' is a double pointer, mostly for the "" (empty string)
  73  * case, where the entire JSON object would be replaced by 'value'.
  74  * In the case of the "" path, the object at '*obj' will have it's refcount
  75  * decremented with 'json_object_put()' and the 'value' object will be assigned to it.
  76  *
  77  * For other cases (JSON sub-objects) ownership of 'value' will be transferred into
  78  * '*obj' via 'json_object_object_add()' & 'json_object_array_put_idx()', so the
  79  * only time the refcount should be decremented for 'value' is when the return value of
  80  * 'json_pointer_set()' is negative (meaning the 'value' object did not get set into '*obj').
  81  *
  82  * That also implies that 'json_pointer_set()' does not do any refcount incrementing.
  83  * (Just that single decrement that was mentioned above).
  84  *
  85  * Note that the 'path' string supports 'printf()' type arguments, so, whatever
  86  * is added after the 'value' param will be treated as an argument for 'path'
  87  * Example: json_pointer_set(obj, "/foo/%d/%s", value, 0, bak)
  88  * This means, that you need to escape '%' with '%%' (just like in printf())
  89  *
  90  * @param obj the json_object instance/tree to which to add a sub-object
  91  * @param path a (RFC6901) string notation for the sub-object to set in the tree
  92  * @param value object to set at path
  93  *
  94  * @return negative if an error (or not found), or 0 if succeeded
  95  */
  96 int json_pointer_set(struct json_object **obj, const char *path, struct json_object *value);
  97
  98 /**
  99  * This is a variant of 'json_pointer_set()' that supports printf() style arguments.
 100  *
 101  * Example: json_pointer_setf(obj, value, "/foo/%d/%s", 0, bak)
 102  * This also means that you need to escape '%' with '%%' (just like in printf())
 103  *
 104  * Please take into consideration all recommended 'printf()' format security
 105  * aspects when using this function.
 106  *
 107  * @param obj the json_object instance/tree to which to add a sub-object
 108  * @param value object to set at path
 109  * @param path_fmt a printf() style format for the path
 110  *
 111  * @return negative if an error (or not found), or 0 if succeeded
 112  */
 113 int json_pointer_setf(struct json_object **obj, struct json_object *value, const char *path_fmt, ...);
 114
 115
 116 #ifdef __cplusplus
 117 }
 118 #endif
 119
 120 #endif