4 * Copyright Metaparadigm Pte. Ltd. 2004.
5 * Michael Clark <michael@metaparadigm.com>
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public (LGPL)
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details: http://www.gnu.org/
19 #ifndef _json_object_h_
20 #define _json_object_h_
22 #define JSON_OBJECT_DEF_HASH_ENTIRES 16
25 #define FALSE ((boolean)0)
28 #define TRUE ((boolean)1)
30 extern char *json_number_chars;
31 extern char *json_hex_chars;
33 /* forward structure definitions */
40 typedef struct json_object json;
42 /* supported object types */
54 /* reference counting functions */
57 * Increment the reference count of json_object
58 * @param this the json_object instance
60 extern struct json_object* json_object_get(struct json_object *this);
63 * Decrement the reference count of json_object and free if it reaches zero
64 * @param this the json_object instance
66 extern void json_object_put(struct json_object *this);
70 * Check if the json_object is of a given type
71 * @param this the json_object instance
80 extern int json_object_is_type(struct json_object *this, enum json_type type);
83 * Get the type of the json_object
84 * @param this the json_object instance
85 * @returns type being one of:
93 extern enum json_type json_object_get_type(struct json_object *this);
96 /** Stringify object to json format
97 * @param this the json_object instance
98 * @returns a string in JSON format
100 extern char* json_object_to_json_string(struct json_object *this);
103 /* object type methods */
105 /** Create a new empty object
106 * @returns a json_object of type json_type_object
108 extern struct json_object* json_object_new_object();
110 /** Get the hashtable of a json_object of type json_type_object
111 * @param this the json_object instance
112 * @returns a linkhash
114 extern struct lh_table* json_object_get_object(struct json_object *this);
116 /** Add an object field to a json_object of type json_type_object
118 * The reference count will *not* be incremented. This is to make adding
119 * fields to objects in code more compact. If you want to retain a reference
120 * to an added object you must wrap the passed object with json_object_get
122 * @param this the json_object instance
123 * @param key the object field name (a private copy will be duplicated)
124 * @param val a json_object or NULL member to associate with the given field
126 extern void json_object_object_add(struct json_object* this, char *key,
127 struct json_object *val);
129 /** Get the json_object associate with a given object field
130 * @param this the json_object instance
131 * @param key the object field name
132 * @returns the json_object associated with the given field name
134 extern struct json_object* json_object_object_get(struct json_object* this,
137 /** Delete the given json_object field
139 * The reference count will be decremented for the deleted object
141 * @param this the json_object instance
142 * @param key the object field name
144 extern void json_object_object_del(struct json_object* this, char *key);
146 /** Iterate through all keys and values of an object
147 * @param this the json_object instance
148 * @param key the local name for the char* key variable defined in the body
149 * @param val the local name for the json_object* object variable defined in the body
151 #define json_object_object_foreach(obj,key,val) \
152 char *key; struct json_object *val; \
153 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 )
156 /* Array type methods */
158 /** Create a new empty json_object of type json_type_array
159 * @returns a json_object of type json_type_array
161 extern struct json_object* json_object_new_array();
163 /** Get the arraylist of a json_object of type json_type_array
164 * @param this the json_object instance
165 * @returns an arraylist
167 extern struct array_list* json_object_get_array(struct json_object *this);
169 /** Get the length of a json_object of type json_type_array
170 * @param this the json_object instance
173 extern int json_object_array_length(struct json_object *this);
175 /** Add an element to the end of a json_object of type json_type_array
177 * The reference count will *not* be incremented. This is to make adding
178 * fields to objects in code more compact. If you want to retain a reference
179 * to an added object you must wrap the passed object with json_object_get
181 * @param this the json_object instance
182 * @param val the json_object to be added
184 extern int json_object_array_add(struct json_object *this,
185 struct json_object *val);
187 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
189 * The reference count will *not* be incremented. This is to make adding
190 * fields to objects in code more compact. If you want to retain a reference
191 * to an added object you must wrap the passed object with json_object_get
193 * The reference count of a replaced object will be decremented.
195 * The array size will be automatically be expanded to the size of the
196 * index if the index is larger than the current size.
198 * @param this the json_object instance
199 * @param idx the index to insert the element at
200 * @param val the json_object to be added
202 extern int json_object_array_put_idx(struct json_object *this, int idx,
203 struct json_object *val);
205 /** Get the element at specificed index of the array (a json_object of type json_type_array)
206 * @param this the json_object instance
207 * @param idx the index to get the element at
208 * @returns the json_object at the specified index (or NULL)
210 extern struct json_object* json_object_array_get_idx(struct json_object *this,
213 /* boolean type methods */
215 /** Create a new empty json_object of type json_type_boolean
216 * @param b a boolean TRUE or FALSE (0 or 1)
217 * @returns a json_object of type json_type_boolean
219 extern struct json_object* json_object_new_boolean(boolean b);
221 /** Get the boolean value of a json_object
223 * The type is coerced to a boolean if the passed object is not a boolean.
224 * integer and double objects will return FALSE if there value is zero
225 * or TRUE otherwise. If the passed object is a string it will return
226 * TRUE if it has a non zero length. If any other object type is passed
227 * TRUE will be returned if the object is not NULL.
229 * @param this the json_object instance
232 extern boolean json_object_get_boolean(struct json_object *this);
235 /* int type methods */
237 /** Create a new empty json_object of type json_type_int
238 * @param i the integer
239 * @returns a json_object of type json_type_int
241 extern struct json_object* json_object_new_int(int i);
243 /** Get the int value of a json_object
245 * The type is coerced to a int if the passed object is not a int.
246 * double objects will return their integer conversion. Strings will be
247 * parsed as an integer. If no conversion exists then 0 is returned.
249 * @param this the json_object instance
252 extern int json_object_get_int(struct json_object *this);
255 /* double type methods */
257 /** Create a new empty json_object of type json_type_double
258 * @param d the double
259 * @returns a json_object of type json_type_double
261 extern struct json_object* json_object_new_double(double d);
263 /** Get the double value of a json_object
265 * The type is coerced to a double if the passed object is not a double.
266 * integer objects will return their dboule conversion. Strings will be
267 * parsed as a double. If no conversion exists then 0.0 is returned.
269 * @param this the json_object instance
272 extern double json_object_get_double(struct json_object *this);
275 /* string type methods */
277 /** Create a new empty json_object of type json_type_string
279 * A copy of the string is made and the memory is managed by the json_object
281 * @param s the string
282 * @returns a json_object of type json_type_string
284 extern struct json_object* json_object_new_string(char *s);
286 extern struct json_object* json_object_new_string_len(char *s, int len);
288 /** Get the string value of a json_object
290 * If the passed object is not of type json_type_string then the JSON
291 * representation of the object is returned.
293 * The returned string memory is managed by the json_object and will
294 * be freed when the reference count of the json_object drops to zero.
296 * @param this the json_object instance
299 extern char* json_object_get_string(struct json_object *this);