Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 1 | /* |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 2 | * $Id: json_object.h,v 1.11 2006/01/26 02:16:28 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> |
| 6 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 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. |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 9 | * |
| 10 | */ |
| 11 | |
| 12 | #ifndef _json_object_h_ |
| 13 | #define _json_object_h_ |
| 14 | |
Michael Clark | 4504df7 | 2007-03-13 08:26:20 +0000 | [diff] [blame] | 15 | #include "config.h" |
| 16 | |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 17 | #define JSON_OBJECT_DEF_HASH_ENTIRES 16 |
| 18 | |
| 19 | #undef FALSE |
| 20 | #define FALSE ((boolean)0) |
| 21 | |
| 22 | #undef TRUE |
| 23 | #define TRUE ((boolean)1) |
| 24 | |
| 25 | extern char *json_number_chars; |
| 26 | extern char *json_hex_chars; |
| 27 | |
| 28 | /* forward structure definitions */ |
| 29 | |
| 30 | typedef int boolean; |
| 31 | struct printbuf; |
| 32 | struct lh_table; |
| 33 | struct array_list; |
| 34 | struct json_object; |
Michael Clark | 4504df7 | 2007-03-13 08:26:20 +0000 | [diff] [blame] | 35 | struct json_object_iter; |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 36 | |
| 37 | /* supported object types */ |
| 38 | |
| 39 | enum json_type { |
| 40 | json_type_null, |
| 41 | json_type_boolean, |
| 42 | json_type_double, |
| 43 | json_type_int, |
| 44 | json_type_object, |
| 45 | json_type_array, |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 46 | json_type_string |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 47 | }; |
| 48 | |
| 49 | /* reference counting functions */ |
| 50 | |
| 51 | /** |
| 52 | * Increment the reference count of json_object |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 53 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 54 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 55 | extern struct json_object* json_object_get(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 56 | |
| 57 | /** |
| 58 | * Decrement the reference count of json_object and free if it reaches zero |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 59 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 60 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 61 | extern void json_object_put(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 62 | |
| 63 | |
| 64 | /** |
| 65 | * Check if the json_object is of a given type |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 66 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 67 | * @param type one of: |
| 68 | json_type_boolean, |
| 69 | json_type_double, |
| 70 | json_type_int, |
| 71 | json_type_object, |
| 72 | json_type_array, |
| 73 | json_type_string, |
| 74 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 75 | 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] | 76 | |
| 77 | /** |
| 78 | * Get the type of the json_object |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 79 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 80 | * @returns type being one of: |
| 81 | json_type_boolean, |
| 82 | json_type_double, |
| 83 | json_type_int, |
| 84 | json_type_object, |
| 85 | json_type_array, |
| 86 | json_type_string, |
| 87 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 88 | extern enum json_type json_object_get_type(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 89 | |
| 90 | |
| 91 | /** Stringify object to json format |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 92 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 93 | * @returns a string in JSON format |
| 94 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 95 | extern char* json_object_to_json_string(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 96 | |
| 97 | |
| 98 | /* object type methods */ |
| 99 | |
| 100 | /** Create a new empty object |
| 101 | * @returns a json_object of type json_type_object |
| 102 | */ |
| 103 | extern struct json_object* json_object_new_object(); |
| 104 | |
| 105 | /** Get the hashtable of a json_object of type json_type_object |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 106 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 107 | * @returns a linkhash |
| 108 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 109 | extern struct lh_table* json_object_get_object(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 110 | |
| 111 | /** Add an object field to a json_object of type json_type_object |
| 112 | * |
| 113 | * The reference count will *not* be incremented. This is to make adding |
| 114 | * fields to objects in code more compact. If you want to retain a reference |
| 115 | * to an added object you must wrap the passed object with json_object_get |
| 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 | * @param key the object field name (a private copy will be duplicated) |
| 119 | * @param val a json_object or NULL member to associate with the given field |
| 120 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 121 | extern void json_object_object_add(struct json_object* obj, char *key, |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 122 | struct json_object *val); |
| 123 | |
| 124 | /** Get the json_object associate with a given object field |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 125 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 126 | * @param key the object field name |
| 127 | * @returns the json_object associated with the given field name |
| 128 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 129 | extern struct json_object* json_object_object_get(struct json_object* obj, |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 130 | char *key); |
| 131 | |
| 132 | /** Delete the given json_object field |
| 133 | * |
| 134 | * The reference count will be decremented for the deleted object |
| 135 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 136 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 137 | * @param key the object field name |
| 138 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 139 | extern void json_object_object_del(struct json_object* obj, char *key); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 140 | |
| 141 | /** Iterate through all keys and values of an object |
Michael Clark | 4504df7 | 2007-03-13 08:26:20 +0000 | [diff] [blame] | 142 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 143 | * @param key the local name for the char* key variable defined in the body |
| 144 | * @param val the local name for the json_object* object variable defined in the body |
| 145 | */ |
Michael Clark | 4504df7 | 2007-03-13 08:26:20 +0000 | [diff] [blame] | 146 | #if defined(__GNUC__) && !defined(__STRICT_ANSI__) |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 147 | |
Michael Clark | 4504df7 | 2007-03-13 08:26:20 +0000 | [diff] [blame] | 148 | # define json_object_object_foreach(obj,key,val) \ |
| 149 | char *key; struct json_object *val; \ |
| 150 | for(struct lh_entry *entry = json_object_get_object(obj)->head; ({ if(entry) { key = (char*)entry->k; val = (struct json_object*)entry->v; } ; entry; }); entry = entry->next ) |
| 151 | |
| 152 | #else /* ANSI C or MSC */ |
| 153 | |
| 154 | # define json_object_object_foreach(obj,key,val) \ |
| 155 | char *key; struct json_object *val; struct lh_entry *entry; \ |
| 156 | for(entry = json_object_get_object(obj)->head; (entry ? (key = (char*)entry->k, val = (struct json_object*)entry->v, entry) : 0); entry = entry->next) |
| 157 | |
| 158 | #endif /* defined(__GNUC__) && !defined(__STRICT_ANSI__) */ |
| 159 | |
| 160 | /** Iterate through all keys and values of an object (ANSI C Safe) |
| 161 | * @param obj the json_object instance |
| 162 | * @param iter the object iterator |
| 163 | */ |
| 164 | #define json_object_object_foreachC(obj,iter) \ |
| 165 | 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] | 166 | |
| 167 | /* Array type methods */ |
| 168 | |
| 169 | /** Create a new empty json_object of type json_type_array |
| 170 | * @returns a json_object of type json_type_array |
| 171 | */ |
| 172 | extern struct json_object* json_object_new_array(); |
| 173 | |
| 174 | /** Get the arraylist of a json_object of type json_type_array |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 175 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 176 | * @returns an arraylist |
| 177 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 178 | extern struct array_list* json_object_get_array(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 179 | |
| 180 | /** Get the length of a json_object of type json_type_array |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 181 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 182 | * @returns an int |
| 183 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 184 | extern int json_object_array_length(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 185 | |
| 186 | /** Add an element to the end of a json_object of type json_type_array |
| 187 | * |
| 188 | * The reference count will *not* be incremented. This is to make adding |
| 189 | * fields to objects in code more compact. If you want to retain a reference |
| 190 | * to an added object you must wrap the passed object with json_object_get |
| 191 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 192 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 193 | * @param val the json_object to be added |
| 194 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 195 | extern int json_object_array_add(struct json_object *obj, |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 196 | struct json_object *val); |
| 197 | |
| 198 | /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array) |
| 199 | * |
| 200 | * The reference count will *not* be incremented. This is to make adding |
| 201 | * fields to objects in code more compact. If you want to retain a reference |
| 202 | * to an added object you must wrap the passed object with json_object_get |
| 203 | * |
| 204 | * The reference count of a replaced object will be decremented. |
| 205 | * |
| 206 | * The array size will be automatically be expanded to the size of the |
| 207 | * index if the index is larger than the current size. |
| 208 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 209 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 210 | * @param idx the index to insert the element at |
| 211 | * @param val the json_object to be added |
| 212 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 213 | 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] | 214 | struct json_object *val); |
| 215 | |
| 216 | /** 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^] | 217 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 218 | * @param idx the index to get the element at |
| 219 | * @returns the json_object at the specified index (or NULL) |
| 220 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 221 | 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] | 222 | int idx); |
| 223 | |
| 224 | /* boolean type methods */ |
| 225 | |
| 226 | /** Create a new empty json_object of type json_type_boolean |
| 227 | * @param b a boolean TRUE or FALSE (0 or 1) |
| 228 | * @returns a json_object of type json_type_boolean |
| 229 | */ |
| 230 | extern struct json_object* json_object_new_boolean(boolean b); |
| 231 | |
| 232 | /** Get the boolean value of a json_object |
| 233 | * |
| 234 | * The type is coerced to a boolean if the passed object is not a boolean. |
| 235 | * integer and double objects will return FALSE if there value is zero |
| 236 | * or TRUE otherwise. If the passed object is a string it will return |
| 237 | * TRUE if it has a non zero length. If any other object type is passed |
| 238 | * TRUE will be returned if the object is not NULL. |
| 239 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 240 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 241 | * @returns a boolean |
| 242 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 243 | extern boolean json_object_get_boolean(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 244 | |
| 245 | |
| 246 | /* int type methods */ |
| 247 | |
| 248 | /** Create a new empty json_object of type json_type_int |
| 249 | * @param i the integer |
| 250 | * @returns a json_object of type json_type_int |
| 251 | */ |
| 252 | extern struct json_object* json_object_new_int(int i); |
| 253 | |
| 254 | /** Get the int value of a json_object |
| 255 | * |
| 256 | * The type is coerced to a int if the passed object is not a int. |
| 257 | * double objects will return their integer conversion. Strings will be |
| 258 | * parsed as an integer. If no conversion exists then 0 is returned. |
| 259 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 260 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 261 | * @returns an int |
| 262 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 263 | extern int json_object_get_int(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 264 | |
| 265 | |
| 266 | /* double type methods */ |
| 267 | |
| 268 | /** Create a new empty json_object of type json_type_double |
| 269 | * @param d the double |
| 270 | * @returns a json_object of type json_type_double |
| 271 | */ |
| 272 | extern struct json_object* json_object_new_double(double d); |
| 273 | |
| 274 | /** Get the double value of a json_object |
| 275 | * |
| 276 | * The type is coerced to a double if the passed object is not a double. |
| 277 | * integer objects will return their dboule conversion. Strings will be |
| 278 | * parsed as a double. If no conversion exists then 0.0 is returned. |
| 279 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 280 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 281 | * @returns an double |
| 282 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 283 | extern double json_object_get_double(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 284 | |
| 285 | |
| 286 | /* string type methods */ |
| 287 | |
| 288 | /** Create a new empty json_object of type json_type_string |
| 289 | * |
| 290 | * A copy of the string is made and the memory is managed by the json_object |
| 291 | * |
| 292 | * @param s the string |
| 293 | * @returns a json_object of type json_type_string |
| 294 | */ |
| 295 | extern struct json_object* json_object_new_string(char *s); |
| 296 | |
| 297 | extern struct json_object* json_object_new_string_len(char *s, int len); |
| 298 | |
| 299 | /** Get the string value of a json_object |
| 300 | * |
| 301 | * If the passed object is not of type json_type_string then the JSON |
| 302 | * representation of the object is returned. |
| 303 | * |
| 304 | * The returned string memory is managed by the json_object and will |
| 305 | * be freed when the reference count of the json_object drops to zero. |
| 306 | * |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 307 | * @param obj the json_object instance |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 308 | * @returns a string |
| 309 | */ |
Michael Clark | f6a6e48 | 2007-03-13 08:26:23 +0000 | [diff] [blame^] | 310 | extern char* json_object_get_string(struct json_object *obj); |
Michael Clark | f0d0888 | 2007-03-13 08:26:18 +0000 | [diff] [blame] | 311 | |
| 312 | #endif |