doc/apiref.rst

   1 *************
   2 API Reference
   3 *************
   4
   5 .. highlight:: c
   6
   7 Preliminaries
   8 =============
   9
  10 All declarations are in :file:`jansson.h`, so it's enough to
  11
  12 ::
  13
  14    #include <jansson.h>
  15
  16 in each source file.
  17
  18 All constants are prefixed ``JSON_`` and other identifiers with
  19 ``json_``. Type names are suffixed with ``_t`` and ``typedef``\ 'd so
  20 that the ``struct`` keyword need not be used.
  21
  22
  23 Value Representation
  24 ====================
  25
  26 The JSON specification (:rfc:`4627`) defines the following data types:
  27 *object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
  28 types are used dynamically; arrays and objects can hold any other data
  29 type, including themselves. For this reason, Jansson's type system is
  30 also dynamic in nature. There's one C type to represent all JSON
  31 values, and this structure knows the type of the JSON value it holds.
  32
  33 .. ctype:: json_t
  34
  35   This data structure is used throughout the library to represent all
  36   JSON values. It always contains the type of the JSON value it holds
  37   and the value's reference count. The rest depends on the type of the
  38   value.
  39
  40 Objects of :ctype:`json_t` are always used through a pointer. There
  41 are APIs for querying the type, manipulating the reference count, and
  42 for constructing and manipulating values of different types.
  43
  44
  45 Type
  46 ----
  47
  48 The type of a JSON value is queried and tested using the following
  49 functions:
  50
  51 .. ctype:: enum json_type
  52
  53    The type of a JSON value. The following members are defined:
  54
  55    +-------------------------+
  56    | :const:`JSON_OBJECT`    |
  57    +-------------------------+
  58    | :const:`JSON_ARRAY`     |
  59    +-------------------------+
  60    | :const:`JSON_STRING`    |
  61    +-------------------------+
  62    | :const:`JSON_INTEGER`   |
  63    +-------------------------+
  64    | :const:`JSON_REAL`      |
  65    +-------------------------+
  66    | :const:`JSON_TRUE`      |
  67    +-------------------------+
  68    | :const:`JSON_FALSE`     |
  69    +-------------------------+
  70    | :const:`JSON_NULL`      |
  71    +-------------------------+
  72
  73    These correspond to JSON object, array, string, number, boolean and
  74    null. A number is represented by either a value of the type
  75    :const:`JSON_INTEGER` or of the type :const:`JSON_REAL`. A true
  76    boolean value is represented by a value of the type
  77    :const:`JSON_TRUE` and false by a value of the type
  78    :const:`JSON_FALSE`.
  79
  80 .. cfunction:: int json_typeof(const json_t *json)
  81
  82    Return the type of the JSON value (a :ctype:`json_type` cast to
  83    :ctype:`int`). This function is actually implemented as a macro for
  84    speed.
  85
  86 .. cfunction:: json_is_object(const json_t *json)
  87                json_is_array(const json_t *json)
  88                json_is_string(const json_t *json)
  89                json_is_integer(const json_t *json)
  90                json_is_real(const json_t *json)
  91                json_is_true(const json_t *json)
  92                json_is_false(const json_t *json)
  93                json_is_null(const json_t *json)
  94
  95    These functions (actually macros) return true (non-zero) for values
  96    of the given type, and false (zero) for values of other types.
  97
  98 .. cfunction:: json_is_number(const json_t *json)
  99
 100    Returns true for values of types :const:`JSON_INTEGER` and
 101    :const:`JSON_REAL`, and false for other types.
 102
 103 .. cfunction:: json_is_boolean(const json_t *json)
 104
 105    Returns true for types :const:`JSON_TRUE` and :const:`JSON_FALSE`,
 106    and false for values of other types.
 107
 108
 109 Reference Count
 110 ---------------
 111
 112 The reference count is used to track whether a value is still in use
 113 or not. When a value is created, it's reference count is set to 1. If
 114 a reference to a value is kept (e.g. a value is stored somewhere for
 115 later use), its reference count is incremented, and when the value is
 116 no longer needed, the reference count is decremented. When the
 117 reference count drops to zero, there are no references left, and the
 118 value can be destroyed.
 119
 120 The following functions are used to manipulate the reference count.
 121
 122 .. cfunction:: json_t *json_incref(json_t *json)
 123
 124    Increment the reference count of *json*.
 125
 126 .. cfunction:: void json_decref(json_t *json)
 127
 128    Decrement the reference count of *json*. As soon as a call to
 129    :cfunc:`json_decref()` drops the reference count to zero, the value
 130    is destroyed and it can no longer be used.
 131
 132 Functions creating new JSON values set the reference count to 1. These
 133 functions are said to return a **new reference**. Other functions
 134 returning (existing) JSON values do not normally increase the
 135 reference count. These functions are said to return a **borrowed
 136 reference**. So, if the user will hold a reference to a value returned
 137 as a borrowed reference, he must call :cfunc:`json_incref`. As soon as
 138 the value is no longer needed, :cfunc:`json_decref` should be called
 139 to release the reference.
 140
 141 Normally, all functions accepting a JSON value as an argument will
 142 manage the reference, i.e. increase and decrease the reference count
 143 as needed. However, some functions **steal** the reference, i.e. they
 144 have the same result as if the user called :cfunc:`json_decref()` on
 145 the argument right after calling the function. These are usually
 146 convenience functions for adding new references to containers and not
 147 to worry about the reference count.
 148
 149 In the following sections it is clearly documented whether a function
 150 will return a new or borrowed reference or steal a reference to its
 151 argument.
 152
 153
 154 True, False and Null
 155 ====================
 156
 157 .. cfunction:: json_t *json_true(void)
 158
 159    .. refcounting:: new
 160
 161    Returns a value of the type :const:`JSON_TRUE`, or *NULL* on
 162    error.
 163
 164 .. cfunction:: json_t *json_false(void)
 165
 166    .. refcounting:: new
 167
 168    Returns a value of the type :const:`JSON_FALSE`, or *NULL* on
 169    error.
 170
 171 .. cfunction:: json_t *json_null(void)
 172
 173    .. refcounting:: new
 174
 175    Returns a value of the type :const:`JSON_NULL`, or *NULL* on
 176    error.
 177
 178
 179 String
 180 ======
 181
 182 .. cfunction:: json_t *json_string(const char *value)
 183
 184    .. refcounting:: new
 185
 186    Returns a new value of the type :const:`JSON_STRING`, or *NULL* on
 187    error. *value* must be a valid UTF-8 encoded Unicode string.
 188
 189 .. cfunction:: const char *json_string_value(const json_t *json)
 190
 191    Returns the associated value of a :const:`JSON_STRING` value as a
 192    null terminated UTF-8 encoded string.
 193
 194
 195 Number
 196 ======
 197
 198 .. cfunction:: json_t *json_integer(int value)
 199
 200    .. refcounting:: new
 201
 202    Returns a new value of the type :const:`JSON_INTEGER`, or *NULL* on
 203    error.
 204
 205 .. cfunction:: int json_integer_value(const json_t *json)
 206
 207    Returns the associated integer value of values of the type
 208    :const:`JSON_INTEGER`, or 0 for values of other types.
 209
 210 .. cfunction:: json_t *json_real(double value)
 211
 212    .. refcounting:: new
 213
 214    Returns a new value of the type :const:`JSON_REAL`, or *NULL* on
 215    error.
 216
 217 .. cfunction:: double json_real_value(const json_t *json)
 218
 219    Returns the associated real value of values of the type
 220    :const:`JSON_INTEGER`, or 0 for values of other types.
 221
 222 In addition to the functions above, there's a common query function
 223 for integers and reals:
 224
 225 .. cfunction:: double json_number_value(const json_t *json)
 226
 227    Returns the value of either ``JSON_INTEGER`` or ``JSON_REAL``, cast
 228    to double regardless of the actual type.
 229
 230
 231 Array
 232 =====
 233
 234 A JSON array is an ordered collection of other JSON values.
 235
 236 .. cfunction:: json_t *json_array(void)
 237
 238    .. refcounting:: new
 239
 240    Returns a new value of the type :const:`JSON_ARRAY`, or *NULL* on
 241    error. Initially, the array is empty.
 242
 243 .. cfunction:: unsigned int json_array_size(const json_t *array)
 244
 245    Returns the number of elements in *array*.
 246
 247 .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
 248
 249    .. refcounting:: borrow
 250
 251    Returns the element in *array* at position *index*, or *NULL* if
 252    *index* is out of range. The valid range for *index* is from 0 to
 253    the return value of :cfunc:`json_array_size()` minus 1.
 254
 255 .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
 256
 257    Replaces the element in *array* at position *index* with *value*.
 258    Returns 0 on success, or -1 if *index* is out of range. The valid
 259    range for *index* is from 0 to the return value of
 260    :cfunc:`json_array_size()` minus 1.
 261
 262 .. cfunction:: int json_array_append(json_t *array, json_t *value)
 263
 264    Appends *value* to the end of *array*, growing the size of *array*
 265    by 1. Returns 0 on success and -1 on error.
 266
 267
 268 Object
 269 ======
 270
 271 A JSON object is a dictionary of key-value pairs, where the key is a
 272 Unicode string and the value is any JSON value.
 273
 274 .. cfunction:: json_t *json_object(void)
 275
 276    .. refcounting:: new
 277
 278    Returns a new value of the type :const:`JSON_OBJECT`, or *NULL* on
 279    error. Initially, the object is empty.
 280
 281 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 282
 283    .. refcounting:: borrow
 284
 285    Get a value corresponding to *key* from *object*. Returns *NULL* if
 286    *key* is not found and on error.
 287
 288 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 289
 290    Set the value of *key* to *value* in *object*. *key* must be a
 291    valid terminated UTF-8 encoded Unicode string. If there already is
 292    a value for *key*, it is replaced by the new value. Returns 0 on
 293    success and -1 on error.
 294
 295 .. cfunction:: int json_object_del(json_t *object, const char *key)
 296
 297    Delete *key* from *object* if it exists. Returns 0 on success, or
 298    -1 if *key* was not found.
 299
 300
 301 The following functions implement an iteration protocol for objects:
 302
 303 .. cfunction:: void *json_object_iter(json_t *object)
 304
 305    Returns an opaque iterator which can be used to iterate over all
 306    key-value pairs in *object*, or *NULL* if *object* is empty.
 307
 308 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 309
 310    Returns an iterator pointing to the next key-value pair in *object*
 311    after *iter*, or *NULL* if the whole object has been iterated
 312    through.
 313
 314 .. cfunction:: const char *json_object_iter_key(void *iter)
 315
 316    Extract the associated key from *iter*.
 317
 318 .. cfunction:: json_t *json_object_iter_value(void *iter)
 319
 320    .. refcounting:: borrow
 321
 322    Extract the associated value from *iter*.
 323
 324
 325 Encoding
 326 ========
 327
 328 This sections describes the functions that can be used to encode
 329 values to JSON. Only objects and arrays can be encoded, since they are
 330 the only valid "root" values of a JSON text.
 331
 332 Each function takes a *flags* parameter that controls some aspects of
 333 how the data is encoded. Its default value is 0. The following macros
 334 can be ORed together to obtain *flags*.
 335
 336 ``JSON_INDENT(n)``
 337    Pretty-print the result, indenting arrays and objects by *n*
 338    spaces. The valid range for *n* is between 0 and 255, other values
 339    result in an undefined output. If ``JSON_INDENT`` is not used or
 340    *n* is 0, no pretty-printing is done and the result is a compact
 341    representation.
 342
 343 The following functions perform the actual JSON encoding. The result
 344 is in UTF-8.
 345
 346 .. cfunction:: char *json_dumps(const json_t *root, uint32_t flags)
 347
 348    Returns the JSON representation of *root* as a string, or *NULL* on
 349    error. *flags* is described above. The return value must be freed
 350    by the caller using :cfunc:`free()`.
 351
 352 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, uint32_t flags)
 353
 354    Write the JSON representation of *root* to the stream *output*.
 355    *flags* is described above. Returns 0 on success and -1 on error.
 356
 357 .. cfunction:: int json_dump_file(const json_t *json, const char *path, uint32_t flags)
 358
 359    Write the JSON representation of *root* to the file *path*. If
 360    *path* already exists, it is overwritten. *flags* is described
 361    above. Returns 0 on success and -1 on error.
 362
 363
 364 Decoding
 365 ========
 366
 367 This sections describes the functions that can be used to decode JSON
 368 text to the Jansson representation of JSON data. The JSON
 369 specification requires that a JSON text is either a serialized array
 370 or object, and this requirement is also enforced with the following
 371 functions.
 372
 373 The only supported character encoding is UTF-8 (which ASCII is a
 374 subset of).
 375
 376 .. ctype:: json_error_t
 377
 378    This data structure is used to return information on decoding
 379    errors from the decoding functions. Its definition is repeated
 380    here::
 381
 382       #define JSON_ERROR_TEXT_LENGTH  160
 383
 384       typedef struct {
 385           char text[JSON_ERROR_TEXT_LENGTH];
 386           int line;
 387       } json_error_t;
 388
 389    *line* is the line number on which the error occurred, or -1 if
 390    this information is not available. *text* contains the error
 391    message (in UTF-8), or an empty string if a message is not
 392    available.
 393
 394    The normal usef of :ctype:`json_error_t` is to allocate it normally
 395    on the stack, and pass a pointer to a decoding function. Example::
 396
 397       int main() {
 398           json_t *json;
 399           json_error_t error;
 400
 401           json = json_load_file("/path/to/file.json", &error);
 402           if(!json) {
 403               /* the error variable contains error information */
 404           }
 405           ...
 406       }
 407
 408    Also note that if the decoding succeeded (``json != NULL`` in the
 409    above example), the contents of ``error`` are unspecified.
 410
 411    All decoding functions also accept *NULL* as the
 412    :ctype:`json_error_t` pointer, in which case no error information
 413    is returned to the caller.
 414
 415 The following functions perform the actual JSON decoding.
 416
 417 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 418
 419    .. refcounting:: new
 420
 421    Decodes the JSON string *input* and returns the array or object it
 422    contains, or *NULL* on error, in which case *error* is filled with
 423    information about the error. See above for discussion on the
 424    *error* parameter.
 425
 426 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 427
 428    .. refcounting:: new
 429
 430    Decodes the JSON text in stream *input* and returns the array or
 431    object it contains, or *NULL* on error, in which case *error* is
 432    filled with information about the error. See above for discussion
 433    on the *error* parameter.
 434
 435 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 436
 437    .. refcounting:: new
 438
 439    Decodes the JSON text in file *path* and returns the array or
 440    object it contains, or *NULL* on error, in which case *error* is
 441    filled with information about the error. See above for discussion
 442    on the *error* parameter.