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