1 /* 2 * $Id: json_object.h,v 1.12 2006/01/30 23:07:57 mclark Exp $ 3 * 4 * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd. 5 * Michael Clark <michael@metaparadigm.com> 6 * Copyright (c) 2009 Hewlett-Packard Development Company, L.P. 7 * 8 * This library is free software; you can redistribute it and/or modify 9 * it under the terms of the MIT license. See COPYING for details. 10 * 11 */ 12 13 #ifndef _json_object_h_ 14 #define _json_object_h_ 15 16 #include "symbol_renames.h" 17 #include "cpl_port.h" 18 19 #include "json_inttypes.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #define JSON_OBJECT_DEF_HASH_ENTRIES 16 26 27 /** 28 * A flag for the json_object_to_json_string_ext() and 29 * json_object_to_file_ext() functions which causes the output 30 * to have no extra whitespace or formatting applied. 31 */ 32 #define JSON_C_TO_STRING_PLAIN 0 33 /** 34 * A flag for the json_object_to_json_string_ext() and 35 * json_object_to_file_ext() functions which causes the output to have 36 * minimal whitespace inserted to make things slightly more readable. 37 */ 38 #define JSON_C_TO_STRING_SPACED (1<<0) 39 /** 40 * A flag for the json_object_to_json_string_ext() and 41 * json_object_to_file_ext() functions which causes 42 * the output to be formatted. 43 * 44 * See the "Two Space Tab" option at http://jsonformatter.curiousconcept.com/ 45 * for an example of the format. 46 */ 47 #define JSON_C_TO_STRING_PRETTY (1<<1) 48 /** 49 * A flag to drop trailing zero for float values 50 */ 51 #define JSON_C_TO_STRING_NOZERO (1<<2) 52 53 #undef FALSE 54 #define FALSE ((json_bool)0) 55 56 #undef TRUE 57 #define TRUE ((json_bool)1) 58 59 extern const char *json_number_chars; 60 extern const char *json_hex_chars; 61 62 /* CAW: added for ANSI C iteration correctness */ 63 struct json_object_iter 64 { 65 char *key; 66 struct json_object *val; 67 struct lh_entry *entry; 68 }; 69 70 /* forward structure definitions */ 71 72 typedef int json_bool; 73 typedef struct printbuf printbuf; 74 typedef struct lh_table lh_table; 75 typedef struct array_list array_list; 76 typedef struct json_object json_object; 77 typedef struct json_object_iter json_object_iter; 78 typedef struct json_tokener json_tokener; 79 80 /** 81 * Type of custom user delete functions. See json_object_set_serializer. 82 */ 83 typedef void (json_object_delete_fn)(struct json_object *jso, void *userdata); 84 85 /** 86 * Type of a custom serialization function. See json_object_set_serializer. 87 */ 88 typedef int (json_object_to_json_string_fn)(struct json_object *jso, 89 struct printbuf *pb, 90 int level, 91 int flags); 92 93 /* supported object types */ 94 95 typedef enum json_type { 96 /* If you change this, be sure to update json_type_to_name() too */ 97 json_type_null, 98 json_type_boolean, 99 json_type_double, 100 json_type_int, 101 json_type_object, 102 json_type_array, 103 json_type_string, 104 } json_type; 105 106 /* reference counting functions */ 107 108 /** 109 * Increment the reference count of json_object, thereby grabbing shared 110 * ownership of obj. 111 * 112 * @param obj the json_object instance 113 */ 114 extern struct json_object* json_object_get(struct json_object *obj); 115 116 /** 117 * Decrement the reference count of json_object and free if it reaches zero. 118 * You must have ownership of obj prior to doing this or you will cause an 119 * imbalance in the reference count. 120 * 121 * @param obj the json_object instance 122 * @returns 1 if the object was freed. 123 */ 124 int CPL_DLL json_object_put(struct json_object *obj); 125 126 /** 127 * Check if the json_object is of a given type 128 * @param obj the json_object instance 129 * @param type one of: 130 json_type_null (i.e. obj == NULL), 131 json_type_boolean, 132 json_type_double, 133 json_type_int, 134 json_type_object, 135 json_type_array, 136 json_type_string, 137 */ 138 extern int json_object_is_type(struct json_object *obj, enum json_type type); 139 140 /** 141 * Get the type of the json_object. See also json_type_to_name() to turn this 142 * into a string suitable, for instance, for logging. 143 * 144 * @param obj the json_object instance 145 * @returns type being one of: 146 json_type_null (i.e. obj == NULL), 147 json_type_boolean, 148 json_type_double, 149 json_type_int, 150 json_type_object, 151 json_type_array, 152 json_type_string, 153 */ 154 extern enum json_type json_object_get_type(struct json_object *obj); 155 156 157 /** Stringify object to json format. 158 * Equivalent to json_object_to_json_string_ext(obj, JSON_C_TO_STRING_SPACED) 159 * @param obj the json_object instance 160 * @returns a string in JSON format 161 */ 162 extern const char* json_object_to_json_string(struct json_object *obj); 163 164 /** Stringify object to json format 165 * @param obj the json_object instance 166 * @param flags formatting options, see JSON_C_TO_STRING_PRETTY and other constants 167 * @returns a string in JSON format 168 */ 169 extern const char CPL_DLL* json_object_to_json_string_ext(struct json_object *obj, int 170 flags); 171 172 /** 173 * Set a custom serialization function to be used when this particular object 174 * is converted to a string by json_object_to_json_string. 175 * 176 * If a custom serializer is already set on this object, any existing 177 * user_delete function is called before the new one is set. 178 * 179 * If to_string_func is NULL, the other parameters are ignored 180 * and the default behaviour is reset. 181 * 182 * The userdata parameter is optional and may be passed as NULL. If provided, 183 * it is passed to to_string_func as-is. This parameter may be NULL even 184 * if user_delete is non-NULL. 185 * 186 * The user_delete parameter is optional and may be passed as NULL, even if 187 * the userdata parameter is non-NULL. It will be called just before the 188 * json_object is deleted, after it's reference count goes to zero 189 * (see json_object_put()). 190 * If this is not provided, it is up to the caller to free the userdata at 191 * an appropriate time. (i.e. after the json_object is deleted) 192 * 193 * @param jso the object to customize 194 * @param to_string_func the custom serialization function 195 * @param userdata an optional opaque cookie 196 * @param user_delete an optional function from freeing userdata 197 */ 198 /* GDAL added */ extern void json_object_set_serializer(json_object *jso, 199 json_object_to_json_string_fn to_string_func, 200 void *userdata, 201 json_object_delete_fn *user_delete); 202 203 204 205 /* object type methods */ 206 207 /** Create a new empty object with a reference count of 1. The caller of 208 * this object initially has sole ownership. Remember, when using 209 * json_object_object_add or json_object_array_put_idx, ownership will 210 * transfer to the object/array. Call json_object_get if you want to maintain 211 * shared ownership or also add this object as a child of multiple objects or 212 * arrays. Any ownerships you acquired but did not transfer must be released 213 * through json_object_put. 214 * 215 * @returns a json_object of type json_type_object 216 */ 217 extern struct json_object CPL_DLL* json_object_new_object(void); 218 219 /** Get the hashtable of a json_object of type json_type_object 220 * @param obj the json_object instance 221 * @returns a linkhash 222 */ 223 extern struct lh_table* json_object_get_object(struct json_object *obj); 224 225 /** Get the size of an object in terms of the number of fields it has. 226 * @param obj the json_object whose length to return 227 */ 228 extern int json_object_object_length(struct json_object* obj); 229 230 /** Add an object field to a json_object of type json_type_object 231 * 232 * The reference count will *not* be incremented. This is to make adding 233 * fields to objects in code more compact. If you want to retain a reference 234 * to an added object, independent of the lifetime of obj, you must wrap the 235 * passed object with json_object_get. 236 * 237 * Upon calling this, the ownership of val transfers to obj. Thus you must 238 * make sure that you do in fact have ownership over this object. For instance, 239 * json_object_new_object will give you ownership until you transfer it, 240 * whereas json_object_object_get does not. 241 * 242 * @param obj the json_object instance 243 * @param key the object field name (a private copy will be duplicated) 244 * @param val a json_object or NULL member to associate with the given field 245 */ 246 extern void CPL_DLL json_object_object_add(struct json_object* obj, const char *key, 247 struct json_object *val); 248 249 /** Get the json_object associate with a given object field 250 * 251 * *No* reference counts will be changed. There is no need to manually adjust 252 * reference counts through the json_object_put/json_object_get methods unless 253 * you need to have the child (value) reference maintain a different lifetime 254 * than the owning parent (obj). Ownership of the returned value is retained 255 * by obj (do not do json_object_put unless you have done a json_object_get). 256 * If you delete the value from obj (json_object_object_del) and wish to access 257 * the returned reference afterwards, make sure you have first gotten shared 258 * ownership through json_object_get (& don't forget to do a json_object_put 259 * or transfer ownership to prevent a memory leak). 260 * 261 * @param obj the json_object instance 262 * @param key the object field name 263 * @returns the json_object associated with the given field name 264 */ 265 extern struct json_object* json_object_object_get(struct json_object* obj, 266 const char *key); 267 268 /** Get the json_object associated with a given object field. 269 * 270 * This returns true if the key is found, false in all other cases (including 271 * if obj isn't a json_type_object). 272 * 273 * *No* reference counts will be changed. There is no need to manually adjust 274 * reference counts through the json_object_put/json_object_get methods unless 275 * you need to have the child (value) reference maintain a different lifetime 276 * than the owning parent (obj). Ownership of value is retained by obj. 277 * 278 * @param obj the json_object instance 279 * @param key the object field name 280 * @param value a pointer where to store a reference to the json_object 281 * associated with the given field name. 282 * 283 * It is safe to pass a NULL value. 284 * @returns whether or not the key exists 285 */ 286 extern json_bool json_object_object_get_ex(struct json_object* obj, 287 const char *key, 288 struct json_object **value); 289 290 /** Delete the given json_object field 291 * 292 * The reference count will be decremented for the deleted object. If there 293 * are no more owners of the value represented by this key, then the value is 294 * freed. Otherwise, the reference to the value will remain in memory. 295 * 296 * @param obj the json_object instance 297 * @param key the object field name 298 */ 299 extern void json_object_object_del(struct json_object* obj, const char *key); 300 301 /** 302 * Iterate through all keys and values of an object. 303 * 304 * Adding keys to the object while iterating is NOT allowed. 305 * 306 * Deleting an existing key, or replacing an existing key with a 307 * new value IS allowed. 308 * 309 * @param obj the json_object instance 310 * @param key the local name for the char* key variable defined in the body 311 * @param val the local name for the json_object* object variable defined in 312 * the body 313 */ 314 #if defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L 315 316 # define json_object_object_foreach(obj,key,val) \ 317 char *key; \ 318 struct json_object *val __attribute__((__unused__)); \ 319 for(struct lh_entry *entry ## key = json_object_get_object(obj)->head, *entry_next ## key = NULL; \ 320 ({ if(entry ## key) { \ 321 key = (char*)entry ## key->k; \ 322 val = (struct json_object*)entry ## key->v; \ 323 entry_next ## key = entry ## key->next; \ 324 } ; entry ## key; }); \ 325 entry ## key = entry_next ## key ) 326 327 #else /* ANSI C or MSC */ 328 329 # define json_object_object_foreach(obj,key,val) \ 330 char *key;\ 331 struct json_object *val; \ 332 struct lh_entry *entry ## key; \ 333 struct lh_entry *entry_next ## key = NULL; \ 334 for(entry ## key = json_object_get_object(obj)->head; \ 335 (entry ## key ? ( \ 336 key = (char*)entry ## key->k, \ 337 val = (struct json_object*)entry ## key->v, \ 338 entry_next ## key = entry ## key->next, \ 339 entry ## key) : 0); \ 340 entry ## key = entry_next ## key) 341 342 #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) && __STDC_VERSION__ >= 199901L */ 343 344 /** Iterate through all keys and values of an object (ANSI C Safe) 345 * @param obj the json_object instance 346 * @param iter the object iterator 347 */ 348 #define json_object_object_foreachC(obj,iter) \ 349 for(iter.entry = json_object_get_object(obj)->head; (iter.entry ? (iter.key = (char*)iter.entry->k, iter.val = (struct json_object*)iter.entry->v, iter.entry) : 0); iter.entry = iter.entry->next) 350 351 /* Array type methods */ 352 353 /** Create a new empty json_object of type json_type_array 354 * @returns a json_object of type json_type_array 355 */ 356 extern struct json_object CPL_DLL * json_object_new_array(void); 357 358 /** Get the arraylist of a json_object of type json_type_array 359 * @param obj the json_object instance 360 * @returns an arraylist 361 */ 362 extern struct array_list* json_object_get_array(struct json_object *obj); 363 364 /** Get the length of a json_object of type json_type_array 365 * @param obj the json_object instance 366 * @returns an int 367 */ 368 extern int json_object_array_length(struct json_object *obj); 369 370 /** Sorts the elements of jso of type json_type_array 371 * 372 * Pointers to the json_object pointers will be passed as the two arguments 373 * to @sort_fn 374 * 375 * @param obj the json_object instance 376 * @param sort_fn a sorting function 377 */ 378 extern void json_object_array_sort(struct json_object *jso, int(*sort_fn)(const void *, const void *)); 379 380 /** Add an element to the end of a json_object of type json_type_array 381 * 382 * The reference count will *not* be incremented. This is to make adding 383 * fields to objects in code more compact. If you want to retain a reference 384 * to an added object you must wrap the passed object with json_object_get 385 * 386 * @param obj the json_object instance 387 * @param val the json_object to be added 388 */ 389 extern int CPL_DLL json_object_array_add(struct json_object *obj, 390 struct json_object *val); 391 392 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array) 393 * 394 * The reference count will *not* be incremented. This is to make adding 395 * fields to objects in code more compact. If you want to retain a reference 396 * to an added object you must wrap the passed object with json_object_get 397 * 398 * The reference count of a replaced object will be decremented. 399 * 400 * The array size will be automatically be expanded to the size of the 401 * index if the index is larger than the current size. 402 * 403 * @param obj the json_object instance 404 * @param idx the index to insert the element at 405 * @param val the json_object to be added 406 */ 407 extern int json_object_array_put_idx(struct json_object *obj, int idx, 408 struct json_object *val); 409 410 /** Get the element at specificed index of the array (a json_object of type json_type_array) 411 * @param obj the json_object instance 412 * @param idx the index to get the element at 413 * @returns the json_object at the specified index (or NULL) 414 */ 415 extern struct json_object* json_object_array_get_idx(struct json_object *obj, 416 int idx); 417 418 /* json_bool type methods */ 419 420 /** Create a new empty json_object of type json_type_boolean 421 * @param b a json_bool TRUE or FALSE (0 or 1) 422 * @returns a json_object of type json_type_boolean 423 */ 424 extern struct json_object* json_object_new_boolean(json_bool b); 425 426 /** Get the json_bool value of a json_object 427 * 428 * The type is coerced to a json_bool if the passed object is not a json_bool. 429 * integer and double objects will return FALSE if there value is zero 430 * or TRUE otherwise. If the passed object is a string it will return 431 * TRUE if it has a non zero length. If any other object type is passed 432 * TRUE will be returned if the object is not NULL. 433 * 434 * @param obj the json_object instance 435 * @returns a json_bool 436 */ 437 extern json_bool json_object_get_boolean(struct json_object *obj); 438 439 440 /* int type methods */ 441 442 /** Create a new empty json_object of type json_type_int 443 * Note that values are stored as 64-bit values internally. 444 * To ensure the full range is maintained, use json_object_new_int64 instead. 445 * @param i the integer 446 * @returns a json_object of type json_type_int 447 */ 448 extern struct json_object CPL_DLL* json_object_new_int(int32_t i); 449 450 451 /** Create a new empty json_object of type json_type_int 452 * @param i the integer 453 * @returns a json_object of type json_type_int 454 */ 455 extern struct json_object CPL_DLL* json_object_new_int64(int64_t i); 456 457 458 /** Get the int value of a json_object 459 * 460 * The type is coerced to a int if the passed object is not a int. 461 * double objects will return their integer conversion. Strings will be 462 * parsed as an integer. If no conversion exists then 0 is returned 463 * and errno is set to EINVAL. null is equivalent to 0 (no error values set) 464 * 465 * Note that integers are stored internally as 64-bit values. 466 * If the value of too big or too small to fit into 32-bit, INT32_MAX or 467 * INT32_MIN are returned, respectively. 468 * 469 * @param obj the json_object instance 470 * @returns an int 471 */ 472 extern int32_t json_object_get_int(struct json_object *obj); 473 474 /** Get the int value of a json_object 475 * 476 * The type is coerced to a int64 if the passed object is not a int64. 477 * double objects will return their int64 conversion. Strings will be 478 * parsed as an int64. If no conversion exists then 0 is returned. 479 * 480 * NOTE: Set errno to 0 directly before a call to this function to determine 481 * whether or not conversion was successful (it does not clear the value for 482 * you). 483 * 484 * @param obj the json_object instance 485 * @returns an int64 486 */ 487 extern int64_t json_object_get_int64(struct json_object *obj); 488 489 490 /* double type methods */ 491 492 /** Create a new empty json_object of type json_type_double 493 * @param d the double 494 * @returns a json_object of type json_type_double 495 */ 496 extern struct json_object CPL_DLL* json_object_new_double(double d); 497 498 /** Get the double floating point value of a json_object 499 * 500 * The type is coerced to a double if the passed object is not a double. 501 * integer objects will return their double conversion. Strings will be 502 * parsed as a double. If no conversion exists then 0.0 is returned and 503 * errno is set to EINVAL. null is equivalent to 0 (no error values set) 504 * 505 * If the value is too big to fit in a double, then the value is set to 506 * the closest infinity with errno set to ERANGE. If strings cannot be 507 * converted to their double value, then EINVAL is set & NaN is returned. 508 * 509 * Arrays of length 0 are interpreted as 0 (with no error flags set). 510 * Arrays of length 1 are effectively cast to the equivalent object and 511 * converted using the above rules. All other arrays set the error to 512 * EINVAL & return NaN. 513 * 514 * NOTE: Set errno to 0 directly before a call to this function to 515 * determine whether or not conversion was successful (it does not clear 516 * the value for you). 517 * 518 * @param obj the json_object instance 519 * @returns a double floating point number 520 */ 521 extern double json_object_get_double(struct json_object *obj); 522 523 524 /* string type methods */ 525 526 /** Create a new empty json_object of type json_type_string 527 * 528 * A copy of the string is made and the memory is managed by the json_object 529 * 530 * @param s the string 531 * @returns a json_object of type json_type_string 532 */ 533 extern struct json_object CPL_DLL* json_object_new_string(const char *s); 534 535 extern struct json_object* json_object_new_string_len(const char *s, int len); 536 537 /** Get the string value of a json_object 538 * 539 * If the passed object is not of type json_type_string then the JSON 540 * representation of the object is returned. 541 * 542 * The returned string memory is managed by the json_object and will 543 * be freed when the reference count of the json_object drops to zero. 544 * 545 * @param obj the json_object instance 546 * @returns a string 547 */ 548 extern const char* json_object_get_string(struct json_object *obj); 549 550 /** Get the string length of a json_object 551 * 552 * If the passed object is not of type json_type_string then zero 553 * will be returned. 554 * 555 * @param obj the json_object instance 556 * @returns int 557 */ 558 extern int json_object_get_string_len(struct json_object *obj); 559 560 #ifdef __cplusplus 561 } 562 #endif 563 564 #endif 565