root/src/json-lib/json_object.h

Revision f632f7d9a1b4222c469abf2fc43923fe4868fe37, 10.5 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 3 years ago)

provide overflow detection and recover for json_objects and leverage that in the lua stuff

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