OpenSRF/src/libjson/json_object.h

   1 /*
   2  * $Id$
   3  *
   4  * Copyright Metaparadigm Pte. Ltd. 2004.
   5  * Michael Clark <michael@metaparadigm.com>
   6  *
   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.
  11  *
  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/
  16  *
  17  */
  18
  19 #ifndef _json_object_h_
  20 #define _json_object_h_
  21
  22 #define JSON_OBJECT_DEF_HASH_ENTIRES 16
  23
  24 #undef FALSE
  25 #define FALSE ((boolean)0)
  26
  27 #undef TRUE
  28 #define TRUE ((boolean)1)
  29
  30 extern char *json_number_chars;
  31 extern char *json_hex_chars;
  32
  33 /* forward structure definitions */
  34
  35 typedef int boolean;
  36 struct printbuf;
  37 struct lh_table;
  38 struct array_list;
  39 struct json_object;
  40 typedef struct json_object json;
  41
  42 /* supported object types */
  43
  44 enum json_type {
  45   json_type_null,
  46   json_type_boolean,
  47   json_type_double,
  48   json_type_int,
  49   json_type_object,
  50   json_type_array,
  51   json_type_string,
  52 };
  53
  54 /* reference counting functions */
  55
  56 /**
  57  * Increment the reference count of json_object
  58  * @param this the json_object instance
  59  */
  60 extern struct json_object* json_object_get(struct json_object *this);
  61
  62 /**
  63  * Decrement the reference count of json_object and free if it reaches zero
  64  * @param this the json_object instance
  65  */
  66 extern void json_object_put(struct json_object *this);
  67
  68
  69 /**
  70  * Check if the json_object is of a given type
  71  * @param this the json_object instance
  72  * @param type one of:
  73      json_type_boolean,
  74      json_type_double,
  75      json_type_int,
  76      json_type_object,
  77      json_type_array,
  78      json_type_string,
  79  */
  80 extern int json_object_is_type(struct json_object *this, enum json_type type);
  81
  82 /**
  83  * Get the type of the json_object
  84  * @param this the json_object instance
  85  * @returns type being one of:
  86      json_type_boolean,
  87      json_type_double,
  88      json_type_int,
  89      json_type_object,
  90      json_type_array,
  91      json_type_string,
  92  */
  93 extern enum json_type json_object_get_type(struct json_object *this);
  94
  95
  96 /** Stringify object to json format
  97  * @param this the json_object instance
  98  * @returns a string in JSON format
  99  */
 100 extern char* json_object_to_json_string(struct json_object *this);
 101
 102
 103 /* object type methods */
 104
 105 /** Create a new empty object
 106  * @returns a json_object of type json_type_object
 107  */
 108 extern struct json_object* json_object_new_object();
 109
 110 /** Get the hashtable of a json_object of type json_type_object
 111  * @param this the json_object instance
 112  * @returns a linkhash
 113  */
 114 extern struct lh_table* json_object_get_object(struct json_object *this);
 115
 116 /** Add an object field to a json_object of type json_type_object
 117  *
 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
 121  *
 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
 125  */
 126 extern void json_object_object_add(struct json_object* this, char *key,
 127                                    struct json_object *val);
 128
 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
 133  */
 134 extern struct json_object* json_object_object_get(struct json_object* this,
 135                                                   char *key);
 136
 137 /** Delete the given json_object field
 138  *
 139  * The reference count will be decremented for the deleted object
 140  *
 141  * @param this the json_object instance
 142  * @param key the object field name
 143  */
 144 extern void json_object_object_del(struct json_object* this, char *key);
 145
 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
 150  */
 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 )
 154
 155
 156 /* Array type methods */
 157
 158 /** Create a new empty json_object of type json_type_array
 159  * @returns a json_object of type json_type_array
 160  */
 161 extern struct json_object* json_object_new_array();
 162
 163 /** Get the arraylist of a json_object of type json_type_array
 164  * @param this the json_object instance
 165  * @returns an arraylist
 166  */
 167 extern struct array_list* json_object_get_array(struct json_object *this);
 168
 169 /** Get the length of a json_object of type json_type_array
 170  * @param this the json_object instance
 171  * @returns an int
 172  */
 173 extern int json_object_array_length(struct json_object *this);
 174
 175 /** Add an element to the end of a json_object of type json_type_array
 176  *
 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
 180  *
 181  * @param this the json_object instance
 182  * @param val the json_object to be added
 183  */
 184 extern int json_object_array_add(struct json_object *this,
 185                                  struct json_object *val);
 186
 187 /** Insert or replace an element at a specified index in an array (a json_object of type json_type_array)
 188  *
 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
 192  *
 193  * The reference count of a replaced object will be decremented.
 194  *
 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.
 197  *
 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
 201  */
 202 extern int json_object_array_put_idx(struct json_object *this, int idx,
 203                                      struct json_object *val);
 204
 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)
 209  */
 210 extern struct json_object* json_object_array_get_idx(struct json_object *this,
 211                                                      int idx);
 212
 213 /* boolean type methods */
 214
 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
 218  */
 219 extern struct json_object* json_object_new_boolean(boolean b);
 220
 221 /** Get the boolean value of a json_object
 222  *
 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.
 228  *
 229  * @param this the json_object instance
 230  * @returns a boolean
 231  */
 232 extern boolean json_object_get_boolean(struct json_object *this);
 233
 234
 235 /* int type methods */
 236
 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
 240  */
 241 extern struct json_object* json_object_new_int(int i);
 242
 243 /** Get the int value of a json_object
 244  *
 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.
 248  *
 249  * @param this the json_object instance
 250  * @returns an int
 251  */
 252 extern int json_object_get_int(struct json_object *this);
 253
 254
 255 /* double type methods */
 256
 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
 260  */
 261 extern struct json_object* json_object_new_double(double d);
 262
 263 /** Get the double value of a json_object
 264  *
 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.
 268  *
 269  * @param this the json_object instance
 270  * @returns an double
 271  */
 272 extern double json_object_get_double(struct json_object *this);
 273
 274
 275 /* string type methods */
 276
 277 /** Create a new empty json_object of type json_type_string
 278  *
 279  * A copy of the string is made and the memory is managed by the json_object
 280  *
 281  * @param s the string
 282  * @returns a json_object of type json_type_string
 283  */
 284 extern struct json_object* json_object_new_string(char *s);
 285
 286 extern struct json_object* json_object_new_string_len(char *s, int len);
 287
 288 /** Get the string value of a json_object
 289  *
 290  * If the passed object is not of type json_type_string then the JSON
 291  * representation of the object is returned.
 292  *
 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.
 295  *
 296  * @param this the json_object instance
 297  * @returns a string
 298  */
 299 extern char* json_object_get_string(struct json_object *this);
 300
 301 #endif