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