1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2016 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 /** 7 * \file 8 * JSON parsing and encoding 9 */ 10 11 #ifndef SPDK_JSON_H_ 12 #define SPDK_JSON_H_ 13 14 #include "spdk/stdinc.h" 15 #include "spdk/uuid.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 enum spdk_json_val_type { 22 SPDK_JSON_VAL_INVALID = 0, 23 #define SPDK_JSON_VAL_ANY SPDK_JSON_VAL_INVALID 24 SPDK_JSON_VAL_NULL = 1U << 1, 25 SPDK_JSON_VAL_TRUE = 1U << 2, 26 SPDK_JSON_VAL_FALSE = 1U << 3, 27 SPDK_JSON_VAL_NUMBER = 1U << 4, 28 SPDK_JSON_VAL_STRING = 1U << 5, 29 SPDK_JSON_VAL_ARRAY_BEGIN = 1U << 6, 30 SPDK_JSON_VAL_ARRAY_END = 1U << 7, 31 SPDK_JSON_VAL_OBJECT_BEGIN = 1U << 8, 32 SPDK_JSON_VAL_OBJECT_END = 1U << 9, 33 SPDK_JSON_VAL_NAME = 1U << 10, 34 }; 35 36 struct spdk_json_val { 37 /** 38 * Pointer to the location of the value within the parsed JSON input. 39 * 40 * For SPDK_JSON_VAL_STRING and SPDK_JSON_VAL_NAME, 41 * this points to the beginning of the decoded UTF-8 string without quotes. 42 * 43 * For SPDK_JSON_VAL_NUMBER, this points to the beginning of the number as represented in 44 * the original JSON (text representation, not converted to a numeric value). 45 * 46 * For JSON objects and arrays, this points to their beginning and has a type 47 * set to SPDK_JSON_VAL_OBJECT_BEGIN or SPDK_JSON_VAL_ARRAY_BEGIN respectively. 48 */ 49 void *start; 50 51 /** 52 * Length of value. 53 * 54 * For SPDK_JSON_VAL_STRING, SPDK_JSON_VAL_NUMBER, and SPDK_JSON_VAL_NAME, 55 * this is the length in bytes of the value starting at \ref start. 56 * 57 * For SPDK_JSON_VAL_ARRAY_BEGIN and SPDK_JSON_VAL_OBJECT_BEGIN, 58 * this is the number of values contained within the array or object (including 59 * nested objects and arrays, but not including the _END value). The array or object _END 60 * value can be found by advancing len values from the _BEGIN value. 61 */ 62 uint32_t len; 63 64 /** 65 * Type of value. 66 */ 67 enum spdk_json_val_type type; 68 }; 69 70 /** 71 * Invalid JSON syntax. 72 */ 73 #define SPDK_JSON_PARSE_INVALID -1 74 75 /** 76 * JSON was valid up to the end of the current buffer, but did not represent a complete JSON value. 77 */ 78 #define SPDK_JSON_PARSE_INCOMPLETE -2 79 80 #define SPDK_JSON_PARSE_MAX_DEPTH_EXCEEDED -3 81 82 /** 83 * Decode JSON strings and names in place (modify the input buffer). 84 */ 85 #define SPDK_JSON_PARSE_FLAG_DECODE_IN_PLACE 0x000000001 86 87 /** 88 * Allow parsing of comments. 89 * 90 * Comments are not allowed by the JSON RFC, so this is not enabled by default. 91 */ 92 #define SPDK_JSON_PARSE_FLAG_ALLOW_COMMENTS 0x000000002 93 94 /* 95 * Parse JSON data. 96 * 97 * \param data Raw JSON data; must be encoded in UTF-8. 98 * Note that the data may be modified to perform in-place string decoding. 99 * 100 * \param size Size of data in bytes. 101 * 102 * \param end If non-NULL, this will be filled a pointer to the byte just beyond the end 103 * of the valid JSON. 104 * 105 * \return Number of values parsed, or negative on failure: 106 * SPDK_JSON_PARSE_INVALID if the provided data was not valid JSON, or 107 * SPDK_JSON_PARSE_INCOMPLETE if the provided data was not a complete JSON value. 108 */ 109 ssize_t spdk_json_parse(void *json, size_t size, struct spdk_json_val *values, size_t num_values, 110 void **end, uint32_t flags); 111 112 typedef int (*spdk_json_decode_fn)(const struct spdk_json_val *val, void *out); 113 114 struct spdk_json_object_decoder { 115 const char *name; 116 size_t offset; 117 spdk_json_decode_fn decode_func; 118 bool optional; 119 }; 120 121 int spdk_json_decode_object(const struct spdk_json_val *values, 122 const struct spdk_json_object_decoder *decoders, size_t num_decoders, void *out); 123 int spdk_json_decode_object_relaxed(const struct spdk_json_val *values, 124 const struct spdk_json_object_decoder *decoders, size_t num_decoders, void *out); 125 126 /** 127 * Decode a JSON array. 128 * 129 * \param values List of values to decode. 130 * \param decode_func Function to use to decode each individual value. 131 * \param out Buffer to store decoded value(s). If `stride` != 0, this buffer is advanced `stride` 132 * bytes for each decoded value. 133 * \param out_size Number of decoded values. 134 * \param max_size Maximum number of array elements to decode. 135 * \param stride Number of bytes to advance `out`. 136 * 137 * \return 0 on success, -1 on failure. 138 */ 139 int spdk_json_decode_array(const struct spdk_json_val *values, spdk_json_decode_fn decode_func, 140 void *out, size_t max_size, size_t *out_size, size_t stride); 141 142 int spdk_json_decode_bool(const struct spdk_json_val *val, void *out); 143 int spdk_json_decode_uint8(const struct spdk_json_val *val, void *out); 144 int spdk_json_decode_uint16(const struct spdk_json_val *val, void *out); 145 int spdk_json_decode_int32(const struct spdk_json_val *val, void *out); 146 int spdk_json_decode_uint32(const struct spdk_json_val *val, void *out); 147 int spdk_json_decode_uint64(const struct spdk_json_val *val, void *out); 148 int spdk_json_decode_string(const struct spdk_json_val *val, void *out); 149 int spdk_json_decode_uuid(const struct spdk_json_val *val, void *out); 150 151 void spdk_json_free_object(const struct spdk_json_object_decoder *decoders, size_t num_decoders, 152 void *obj); 153 154 /** 155 * Get length of a value in number of values. 156 * 157 * This can be used to skip over a value while interpreting parse results. 158 * 159 * For SPDK_JSON_VAL_ARRAY_BEGIN and SPDK_JSON_VAL_OBJECT_BEGIN, 160 * this returns the number of values contained within this value, plus the _BEGIN and _END values. 161 * 162 * For all other values, this returns 1. 163 */ 164 size_t spdk_json_val_len(const struct spdk_json_val *val); 165 166 /** 167 * Compare JSON string with null terminated C string. 168 * 169 * \return true if strings are equal or false if not 170 */ 171 bool spdk_json_strequal(const struct spdk_json_val *val, const char *str); 172 173 /** 174 * Equivalent of strdup() for JSON string values. 175 * 176 * If val is not representable as a C string (contains embedded '\0' characters), 177 * returns NULL. 178 * 179 * Caller is responsible for passing the result to free() when it is no longer needed. 180 */ 181 char *spdk_json_strdup(const struct spdk_json_val *val); 182 183 int spdk_json_number_to_uint8(const struct spdk_json_val *val, uint8_t *num); 184 int spdk_json_number_to_uint16(const struct spdk_json_val *val, uint16_t *num); 185 int spdk_json_number_to_int32(const struct spdk_json_val *val, int32_t *num); 186 int spdk_json_number_to_uint32(const struct spdk_json_val *val, uint32_t *num); 187 int spdk_json_number_to_uint64(const struct spdk_json_val *val, uint64_t *num); 188 189 struct spdk_json_write_ctx; 190 191 #define SPDK_JSON_WRITE_FLAG_FORMATTED 0x00000001 192 193 typedef int (*spdk_json_write_cb)(void *cb_ctx, const void *data, size_t size); 194 195 struct spdk_json_write_ctx *spdk_json_write_begin(spdk_json_write_cb write_cb, void *cb_ctx, 196 uint32_t flags); 197 int spdk_json_write_end(struct spdk_json_write_ctx *w); 198 int spdk_json_write_null(struct spdk_json_write_ctx *w); 199 int spdk_json_write_bool(struct spdk_json_write_ctx *w, bool val); 200 int spdk_json_write_uint8(struct spdk_json_write_ctx *w, uint8_t val); 201 int spdk_json_write_uint16(struct spdk_json_write_ctx *w, uint16_t val); 202 int spdk_json_write_int32(struct spdk_json_write_ctx *w, int32_t val); 203 int spdk_json_write_uint32(struct spdk_json_write_ctx *w, uint32_t val); 204 int spdk_json_write_int64(struct spdk_json_write_ctx *w, int64_t val); 205 int spdk_json_write_uint64(struct spdk_json_write_ctx *w, uint64_t val); 206 int spdk_json_write_uint128(struct spdk_json_write_ctx *w, uint64_t low_val, uint64_t high_val); 207 int spdk_json_write_double(struct spdk_json_write_ctx *w, double val); 208 int spdk_json_write_string(struct spdk_json_write_ctx *w, const char *val); 209 int spdk_json_write_string_raw(struct spdk_json_write_ctx *w, const char *val, size_t len); 210 int spdk_json_write_bytearray(struct spdk_json_write_ctx *w, const void *val, size_t len); 211 int spdk_json_write_uuid(struct spdk_json_write_ctx *w, const struct spdk_uuid *uuid); 212 213 /** 214 * Write null-terminated UTF-16LE string. 215 * 216 * \param w JSON write context. 217 * \param val UTF-16LE string; must be null terminated. 218 * \return 0 on success or negative on failure. 219 */ 220 int spdk_json_write_string_utf16le(struct spdk_json_write_ctx *w, const uint16_t *val); 221 222 /** 223 * Write UTF-16LE string. 224 * 225 * \param w JSON write context. 226 * \param val UTF-16LE string; may contain embedded null characters. 227 * \param len Length of val in 16-bit code units (i.e. size of string in bytes divided by 2). 228 * \return 0 on success or negative on failure. 229 */ 230 int spdk_json_write_string_utf16le_raw(struct spdk_json_write_ctx *w, const uint16_t *val, 231 size_t len); 232 233 int spdk_json_write_string_fmt(struct spdk_json_write_ctx *w, const char *fmt, 234 ...) __attribute__((__format__(__printf__, 2, 3))); 235 int spdk_json_write_string_fmt_v(struct spdk_json_write_ctx *w, const char *fmt, va_list args); 236 237 int spdk_json_write_array_begin(struct spdk_json_write_ctx *w); 238 int spdk_json_write_array_end(struct spdk_json_write_ctx *w); 239 int spdk_json_write_object_begin(struct spdk_json_write_ctx *w); 240 int spdk_json_write_object_end(struct spdk_json_write_ctx *w); 241 int spdk_json_write_name(struct spdk_json_write_ctx *w, const char *name); 242 int spdk_json_write_name_raw(struct spdk_json_write_ctx *w, const char *name, size_t len); 243 244 int spdk_json_write_val(struct spdk_json_write_ctx *w, const struct spdk_json_val *val); 245 246 /* 247 * Append bytes directly to the output stream without validation. 248 * 249 * Can be used to write values with specific encodings that differ from the JSON writer output. 250 */ 251 int spdk_json_write_val_raw(struct spdk_json_write_ctx *w, const void *data, size_t len); 252 253 /* Utility functions */ 254 int spdk_json_write_named_null(struct spdk_json_write_ctx *w, const char *name); 255 int spdk_json_write_named_bool(struct spdk_json_write_ctx *w, const char *name, bool val); 256 int spdk_json_write_named_uint8(struct spdk_json_write_ctx *w, const char *name, uint8_t val); 257 int spdk_json_write_named_uint16(struct spdk_json_write_ctx *w, const char *name, uint16_t val); 258 int spdk_json_write_named_int32(struct spdk_json_write_ctx *w, const char *name, int32_t val); 259 int spdk_json_write_named_uint32(struct spdk_json_write_ctx *w, const char *name, uint32_t val); 260 int spdk_json_write_named_int64(struct spdk_json_write_ctx *w, const char *name, int64_t val); 261 int spdk_json_write_named_uint64(struct spdk_json_write_ctx *w, const char *name, uint64_t val); 262 int spdk_json_write_named_uint128(struct spdk_json_write_ctx *w, const char *name, 263 uint64_t low_val, uint64_t high_val); 264 int spdk_json_write_named_double(struct spdk_json_write_ctx *w, const char *name, double val); 265 266 int spdk_json_write_named_string(struct spdk_json_write_ctx *w, const char *name, const char *val); 267 int spdk_json_write_named_string_fmt(struct spdk_json_write_ctx *w, const char *name, 268 const char *fmt, ...) __attribute__((__format__(__printf__, 3, 4))); 269 int spdk_json_write_named_string_fmt_v(struct spdk_json_write_ctx *w, const char *name, 270 const char *fmt, va_list args); 271 int spdk_json_write_named_bytearray(struct spdk_json_write_ctx *w, const char *name, 272 const void *val, size_t len); 273 int spdk_json_write_named_uuid(struct spdk_json_write_ctx *w, const char *name, 274 const struct spdk_uuid *uuid); 275 276 int spdk_json_write_named_array_begin(struct spdk_json_write_ctx *w, const char *name); 277 int spdk_json_write_named_object_begin(struct spdk_json_write_ctx *w, const char *name); 278 279 /** 280 * Return JSON value associated with key \c key_name. Subobjects won't be searched. 281 * 282 * \param object JSON object to be examined 283 * \param key_name name of the key 284 * \param key optional, will be set with found key 285 * \param val optional, will be set with value of the key 286 * \param type search for specific value type. Pass SPDK_JSON_VAL_ANY to match any type. 287 * \return 0 if found or negative error code: 288 * -EINVAL - json object is invalid 289 * -ENOENT - key not found 290 * -EDOM - key exists but value type mismatch. 291 * -EPROTOTYPE - json not enclosed in {}. 292 */ 293 int spdk_json_find(struct spdk_json_val *object, const char *key_name, struct spdk_json_val **key, 294 struct spdk_json_val **val, enum spdk_json_val_type type); 295 296 /** 297 * The same as calling \c spdk_json_find() function with \c type set to \c SPDK_JSON_VAL_STRING 298 * 299 * \param object JSON object to be examined 300 * \param key_name name of the key 301 * \param key optional, will be set with found key 302 * \param val optional, will be set with value of the key 303 * \return See \c spdk_json_find 304 */ 305 306 int spdk_json_find_string(struct spdk_json_val *object, const char *key_name, 307 struct spdk_json_val **key, struct spdk_json_val **val); 308 309 /** 310 * The same as calling \c spdk_json_key() function with \c type set to \c SPDK_JSON_VAL_ARRAY_BEGIN 311 * 312 * \param object JSON object to be examined 313 * \param key_name name of the key 314 * \param key optional, will be set with found key 315 * \param value optional, will be set with key value 316 * \return See \c spdk_json_find 317 */ 318 int spdk_json_find_array(struct spdk_json_val *object, const char *key_name, 319 struct spdk_json_val **key, struct spdk_json_val **value); 320 321 /** 322 * Return first JSON value in given JSON object. 323 * 324 * \param object pointer to JSON object begin 325 * \return Pointer to first object or NULL if object is empty or is not an JSON object 326 */ 327 struct spdk_json_val *spdk_json_object_first(struct spdk_json_val *object); 328 329 /** 330 * Return first JSON value in array. 331 * 332 * \param array_begin pointer to JSON array begin 333 * \return Pointer to first JSON value or NULL if array is empty or is not an JSON array. 334 */ 335 336 struct spdk_json_val *spdk_json_array_first(struct spdk_json_val *array_begin); 337 338 /** 339 * Advance to the next JSON value in JSON object or array. 340 * 341 * \warning if \c pos is not JSON key or JSON array element behaviour is undefined. 342 * 343 * \param pos pointer to JSON key if iterating over JSON object or array element 344 * \return next JSON value or NULL if there is no more objects or array elements 345 */ 346 struct spdk_json_val *spdk_json_next(struct spdk_json_val *pos); 347 348 #ifdef __cplusplus 349 } 350 #endif 351 352 #endif 353