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