• source navigation  • diff markup  • identifier search  • freetext search  • 

Sources/json-c/json_object.h

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

This page was automatically generated by LXR 0.3.1.  •  OpenWrt