1 /* 2 * $Id: json_tokener.h,v 1.10 2006/07/25 03:24:50 mclark Exp $ 3 * 4 * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd. 5 * Michael Clark <michael@metaparadigm.com> 6 * 7 * This library is free software; you can redistribute it and/or modify 8 * it under the terms of the MIT license. See COPYING for details. 9 * 10 */ 11 12 /** 13 * @file 14 * @brief Methods to parse an input string into a tree of json_object objects. 15 */ 16 #ifndef _json_tokener_h_ 17 #define _json_tokener_h_ 18 19 #include "json_object.h" 20 #include <stddef.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 enum json_tokener_error 27 { 28 json_tokener_success, 29 json_tokener_continue, 30 json_tokener_error_depth, 31 json_tokener_error_parse_eof, 32 json_tokener_error_parse_unexpected, 33 json_tokener_error_parse_null, 34 json_tokener_error_parse_boolean, 35 json_tokener_error_parse_number, 36 json_tokener_error_parse_array, 37 json_tokener_error_parse_object_key_name, 38 json_tokener_error_parse_object_key_sep, 39 json_tokener_error_parse_object_value_sep, 40 json_tokener_error_parse_string, 41 json_tokener_error_parse_comment, 42 json_tokener_error_parse_utf8_string, 43 json_tokener_error_size 44 }; 45 46 /** 47 * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release. 48 */ 49 enum json_tokener_state 50 { 51 json_tokener_state_eatws, 52 json_tokener_state_start, 53 json_tokener_state_finish, 54 json_tokener_state_null, 55 json_tokener_state_comment_start, 56 json_tokener_state_comment, 57 json_tokener_state_comment_eol, 58 json_tokener_state_comment_end, 59 json_tokener_state_string, 60 json_tokener_state_string_escape, 61 json_tokener_state_escape_unicode, 62 json_tokener_state_escape_unicode_need_escape, 63 json_tokener_state_escape_unicode_need_u, 64 json_tokener_state_boolean, 65 json_tokener_state_number, 66 json_tokener_state_array, 67 json_tokener_state_array_add, 68 json_tokener_state_array_sep, 69 json_tokener_state_object_field_start, 70 json_tokener_state_object_field, 71 json_tokener_state_object_field_end, 72 json_tokener_state_object_value, 73 json_tokener_state_object_value_add, 74 json_tokener_state_object_sep, 75 json_tokener_state_array_after_sep, 76 json_tokener_state_object_field_start_after_sep, 77 json_tokener_state_inf 78 }; 79 80 /** 81 * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release. 82 */ 83 struct json_tokener_srec 84 { 85 enum json_tokener_state state, saved_state; 86 struct json_object *obj; 87 struct json_object *current; 88 char *obj_field_name; 89 }; 90 91 #define JSON_TOKENER_DEFAULT_DEPTH 32 92 93 /** 94 * Internal state of the json parser. 95 * Do not access any fields of this structure directly. 96 * Its definition is published due to historical limitations 97 * in the json tokener API, and will be changed to be an opaque 98 * type in the future. 99 */ 100 struct json_tokener 101 { 102 /** 103 * @deprecated Do not access any of these fields outside of json_tokener.c 104 */ 105 char *str; 106 struct printbuf *pb; 107 int max_depth, depth, is_double, st_pos; 108 /** 109 * @deprecated See json_tokener_get_parse_end() instead. 110 */ 111 int char_offset; 112 /** 113 * @deprecated See json_tokener_get_error() instead. 114 */ 115 enum json_tokener_error err; 116 unsigned int ucs_char, high_surrogate; 117 char quote_char; 118 struct json_tokener_srec *stack; 119 int flags; 120 }; 121 122 /** 123 * Return the offset of the byte after the last byte parsed 124 * relative to the start of the most recent string passed in 125 * to json_tokener_parse_ex(). i.e. this is where parsing 126 * would start again if the input contains another JSON object 127 * after the currently parsed one. 128 * 129 * Note that when multiple parse calls are issued, this is *not* the 130 * total number of characters parsed. 131 * 132 * In the past this would have been accessed as tok->char_offset. 133 * 134 * See json_tokener_parse_ex() for an example of how to use this. 135 */ 136 JSON_EXPORT size_t json_tokener_get_parse_end(struct json_tokener *tok); 137 138 /** 139 * @deprecated Unused in json-c code 140 */ 141 typedef struct json_tokener json_tokener; 142 143 /** 144 * Be strict when parsing JSON input. Use caution with 145 * this flag as what is considered valid may become more 146 * restrictive from one release to the next, causing your 147 * code to fail on previously working input. 148 * 149 * Note that setting this will also effectively disable parsing 150 * of multiple json objects in a single character stream 151 * (e.g. {"foo":123}{"bar":234}); if you want to allow that 152 * also set JSON_TOKENER_ALLOW_TRAILING_CHARS 153 * 154 * This flag is not set by default. 155 * 156 * @see json_tokener_set_flags() 157 */ 158 #define JSON_TOKENER_STRICT 0x01 159 160 /** 161 * Use with JSON_TOKENER_STRICT to allow trailing characters after the 162 * first parsed object. 163 * 164 * @see json_tokener_set_flags() 165 */ 166 #define JSON_TOKENER_ALLOW_TRAILING_CHARS 0x02 167 168 /** 169 * Cause json_tokener_parse_ex() to validate that input is UTF8. 170 * If this flag is specified and validation fails, then 171 * json_tokener_get_error(tok) will return 172 * json_tokener_error_parse_utf8_string 173 * 174 * This flag is not set by default. 175 * 176 * @see json_tokener_set_flags() 177 */ 178 #define JSON_TOKENER_VALIDATE_UTF8 0x10 179 180 /** 181 * Given an error previously returned by json_tokener_get_error(), 182 * return a human readable description of the error. 183 * 184 * @return a generic error message is returned if an invalid error value is provided. 185 */ 186 JSON_EXPORT const char *json_tokener_error_desc(enum json_tokener_error jerr); 187 188 /** 189 * Retrieve the error caused by the last call to json_tokener_parse_ex(), 190 * or json_tokener_success if there is no error. 191 * 192 * When parsing a JSON string in pieces, if the tokener is in the middle 193 * of parsing this will return json_tokener_continue. 194 * 195 * @see json_tokener_error_desc(). 196 */ 197 JSON_EXPORT enum json_tokener_error json_tokener_get_error(struct json_tokener *tok); 198 199 /** 200 * Allocate a new json_tokener. 201 * When done using that to parse objects, free it with json_tokener_free(). 202 * See json_tokener_parse_ex() for usage details. 203 */ 204 JSON_EXPORT struct json_tokener *json_tokener_new(void); 205 206 /** 207 * Allocate a new json_tokener with a custom max nesting depth. 208 * @see JSON_TOKENER_DEFAULT_DEPTH 209 */ 210 JSON_EXPORT struct json_tokener *json_tokener_new_ex(int depth); 211 212 /** 213 * Free a json_tokener previously allocated with json_tokener_new(). 214 */ 215 JSON_EXPORT void json_tokener_free(struct json_tokener *tok); 216 217 /** 218 * Reset the state of a json_tokener, to prepare to parse a 219 * brand new JSON object. 220 */ 221 JSON_EXPORT void json_tokener_reset(struct json_tokener *tok); 222 223 /** 224 * Parse a json_object out of the string `str`. 225 * 226 * If you need more control over how the parsing occurs, 227 * see json_tokener_parse_ex(). 228 */ 229 JSON_EXPORT struct json_object *json_tokener_parse(const char *str); 230 231 /** 232 * Parser a json_object out of the string `str`, but if it fails 233 * return the error in `*error`. 234 * @see json_tokener_parse() 235 * @see json_tokener_parse_ex() 236 */ 237 JSON_EXPORT struct json_object *json_tokener_parse_verbose(const char *str, 238 enum json_tokener_error *error); 239 240 /** 241 * Set flags that control how parsing will be done. 242 */ 243 JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags); 244 245 /** 246 * Parse a string and return a non-NULL json_object if a valid JSON value 247 * is found. The string does not need to be a JSON object or array; 248 * it can also be a string, number or boolean value. 249 * 250 * A partial JSON string can be parsed. If the parsing is incomplete, 251 * NULL will be returned and json_tokener_get_error() will return 252 * json_tokener_continue. 253 * json_tokener_parse_ex() can then be called with additional bytes in str 254 * to continue the parsing. 255 * 256 * If json_tokener_parse_ex() returns NULL and the error is anything other than 257 * json_tokener_continue, a fatal error has occurred and parsing must be 258 * halted. Then, the tok object must not be reused until json_tokener_reset() 259 * is called. 260 * 261 * When a valid JSON value is parsed, a non-NULL json_object will be 262 * returned, with a reference count of one which belongs to the caller. Also, 263 * json_tokener_get_error() will return json_tokener_success. Be sure to check 264 * the type with json_object_is_type() or json_object_get_type() before using 265 * the object. 266 * 267 * Trailing characters after the parsed value do not automatically cause an 268 * error. It is up to the caller to decide whether to treat this as an 269 * error or to handle the additional characters, perhaps by parsing another 270 * json value starting from that point. 271 * 272 * If the caller knows that they are at the end of their input, the length 273 * passed MUST include the final '\0' character, so values with no inherent 274 * end (i.e. numbers) can be properly parsed, rather than just returning 275 * json_tokener_continue. 276 * 277 * Extra characters can be detected by comparing the value returned by 278 * json_tokener_get_parse_end() against 279 * the length of the last len parameter passed in. 280 * 281 * The tokener does \b not maintain an internal buffer so the caller is 282 * responsible for a subsequent call to json_tokener_parse_ex with an 283 * appropriate str parameter starting with the extra characters. 284 * 285 * This interface is presently not 64-bit clean due to the int len argument 286 * so the function limits the maximum string size to INT32_MAX (2GB). 287 * If the function is called with len == -1 then strlen is called to check 288 * the string length is less than INT32_MAX (2GB) 289 * 290 * Example: 291 * @code 292 json_object *jobj = NULL; 293 const char *mystring = NULL; 294 int stringlen = 0; 295 enum json_tokener_error jerr; 296 do { 297 mystring = ... // get JSON string, e.g. read from file, etc... 298 stringlen = strlen(mystring); 299 if (end_of_input) 300 stringlen++; // Include the '\0' if we know we're at the end of input 301 jobj = json_tokener_parse_ex(tok, mystring, stringlen); 302 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue); 303 if (jerr != json_tokener_success) 304 { 305 fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr)); 306 // Handle errors, as appropriate for your application. 307 } 308 if (json_tokener_get_parse_end(tok) < stringlen) 309 { 310 // Handle extra characters after parsed object as desired. 311 // e.g. issue an error, parse another object from that point, etc... 312 } 313 // Success, use jobj here. 314 315 @endcode 316 * 317 * @param tok a json_tokener previously allocated with json_tokener_new() 318 * @param str an string with any valid JSON expression, or portion of. This does not need to be null terminated. 319 * @param len the length of str 320 */ 321 JSON_EXPORT struct json_object *json_tokener_parse_ex(struct json_tokener *tok, const char *str, 322 int len); 323 324 #ifdef __cplusplus 325 } 326 #endif 327 328 #endif 329
This page was automatically generated by LXR 0.3.1. • OpenWrt