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 Unless noted otherwise, all API functions return an error value if an
  45 error occurs. Depending on the function's signature, the error value
  46 is either *NULL* or -1. Invalid arguments or invalid input are
  47 apparent sources for errors. Memory allocation and I/O operations may
  48 also cause errors.
  49
  50
  51 Type
  52 ----
  53
  54 The type of a JSON value is queried and tested using the following
  55 functions:
  56
  57 .. ctype:: enum json_type
  58
  59    The type of a JSON value. The following members are defined:
  60
  61    +-------------------------+
  62    | :const:`JSON_OBJECT`    |
  63    +-------------------------+
  64    | :const:`JSON_ARRAY`     |
  65    +-------------------------+
  66    | :const:`JSON_STRING`    |
  67    +-------------------------+
  68    | :const:`JSON_INTEGER`   |
  69    +-------------------------+
  70    | :const:`JSON_REAL`      |
  71    +-------------------------+
  72    | :const:`JSON_TRUE`      |
  73    +-------------------------+
  74    | :const:`JSON_FALSE`     |
  75    +-------------------------+
  76    | :const:`JSON_NULL`      |
  77    +-------------------------+
  78
  79    These correspond to JSON object, array, string, number, boolean and
  80    null. A number is represented by either a value of the type
  81    :const:`JSON_INTEGER` or of the type :const:`JSON_REAL`. A true
  82    boolean value is represented by a value of the type
  83    :const:`JSON_TRUE` and false by a value of the type
  84    :const:`JSON_FALSE`.
  85
  86 .. cfunction:: int json_typeof(const json_t *json)
  87
  88    Return the type of the JSON value (a :ctype:`json_type` cast to
  89    :ctype:`int`). *json* MUST NOT be *NULL*. This function is actually
  90    implemented as a macro for speed.
  91
  92 .. cfunction:: json_is_object(const json_t *json)
  93                json_is_array(const json_t *json)
  94                json_is_string(const json_t *json)
  95                json_is_integer(const json_t *json)
  96                json_is_real(const json_t *json)
  97                json_is_true(const json_t *json)
  98                json_is_false(const json_t *json)
  99                json_is_null(const json_t *json)
 100
 101    These functions (actually macros) return true (non-zero) for values
 102    of the given type, and false (zero) for values of other types and
 103    for *NULL*.
 104
 105 .. cfunction:: json_is_number(const json_t *json)
 106
 107    Returns true for values of types :const:`JSON_INTEGER` and
 108    :const:`JSON_REAL`, and false for other types and for *NULL*.
 109
 110 .. cfunction:: json_is_boolean(const json_t *json)
 111
 112    Returns true for types :const:`JSON_TRUE` and :const:`JSON_FALSE`,
 113    and false for values of other types and for *NULL*.
 114
 115
 116 Reference Count
 117 ---------------
 118
 119 The reference count is used to track whether a value is still in use
 120 or not. When a value is created, it's reference count is set to 1. If
 121 a reference to a value is kept (e.g. a value is stored somewhere for
 122 later use), its reference count is incremented, and when the value is
 123 no longer needed, the reference count is decremented. When the
 124 reference count drops to zero, there are no references left, and the
 125 value can be destroyed.
 126
 127 The following functions are used to manipulate the reference count.
 128
 129 .. cfunction:: json_t *json_incref(json_t *json)
 130
 131    Increment the reference count of *json* if it's not non-*NULL*.
 132    Returns *json*.
 133
 134 .. cfunction:: void json_decref(json_t *json)
 135
 136    Decrement the reference count of *json*. As soon as a call to
 137    :cfunc:`json_decref()` drops the reference count to zero, the value
 138    is destroyed and it can no longer be used.
 139
 140 Functions creating new JSON values set the reference count to 1. These
 141 functions are said to return a **new reference**. Other functions
 142 returning (existing) JSON values do not normally increase the
 143 reference count. These functions are said to return a **borrowed
 144 reference**. So, if the user will hold a reference to a value returned
 145 as a borrowed reference, he must call :cfunc:`json_incref`. As soon as
 146 the value is no longer needed, :cfunc:`json_decref` should be called
 147 to release the reference.
 148
 149 Normally, all functions accepting a JSON value as an argument will
 150 nmanage the reference, i.e. increase and decrease the reference count
 151 as needed. However, some functions **steal** the reference, i.e. they
 152 have the same result as if the user called :cfunc:`json_decref()` on
 153 the argument right after calling the function. These are usually
 154 convenience functions for adding new references to containers and not
 155 to worry about the reference count.
 156
 157 In the following sections it is clearly documented whether a function
 158 will return a new or borrowed reference or steal a reference to its
 159 argument.
 160
 161
 162 True, False and Null
 163 ====================
 164
 165 These values are implemented as singletons, so each of these functions
 166 returns the same value each time.
 167
 168 .. cfunction:: json_t *json_true(void)
 169
 170    .. refcounting:: new
 171
 172    Returns the JSON true value.
 173
 174 .. cfunction:: json_t *json_false(void)
 175
 176    .. refcounting:: new
 177
 178    Returns the JSON false value.
 179
 180 .. cfunction:: json_t *json_null(void)
 181
 182    .. refcounting:: new
 183
 184    Returns the JSON null value.
 185
 186
 187 String
 188 ======
 189
 190 .. cfunction:: json_t *json_string(const char *value)
 191
 192    .. refcounting:: new
 193
 194    Returns a new JSON string, or *NULL* on error. *value* must be a
 195    valid UTF-8 encoded Unicode string.
 196
 197 .. cfunction:: const char *json_string_value(const json_t *json)
 198
 199    Returns the associated value of the JSON string *json* as a null
 200    terminated UTF-8 encoded string, or *NULL* if *json* is not a JSON
 201    string.
 202
 203
 204 Number
 205 ======
 206
 207 .. cfunction:: json_t *json_integer(int value)
 208
 209    .. refcounting:: new
 210
 211    Returns a new JSON integer, or *NULL* on error.
 212
 213 .. cfunction:: int json_integer_value(const json_t *json)
 214
 215    Returns the associated value the JSON integer *json*. If *json* is
 216    *NULL* or not a JSON integer, 0 is returned.
 217
 218 .. cfunction:: json_t *json_real(double value)
 219
 220    .. refcounting:: new
 221
 222    Returns a new JSON real, or *NULL* on error.
 223
 224 .. cfunction:: double json_real_value(const json_t *json)
 225
 226    Returns the associated value of the JSON real *json*. If *json* is
 227    *NULL* or not a JSON real, 0.0 is returned.
 228
 229 In addition to the functions above, there's a common query function
 230 for integers and reals:
 231
 232 .. cfunction:: double json_number_value(const json_t *json)
 233
 234    Returns the associated value of the JSON integer or JSON real
 235    *json*, cast to double regardless of the actual type. If *json* is
 236    neither JSON real nor JSON integer, 0.0 is returned.
 237
 238
 239 Array
 240 =====
 241
 242 A JSON array is an ordered collection of other JSON values.
 243
 244 .. cfunction:: json_t *json_array(void)
 245
 246    .. refcounting:: new
 247
 248    Returns a new JSON array, or *NULL* on error. Initially, the array
 249    is empty.
 250
 251 .. cfunction:: unsigned int json_array_size(const json_t *array)
 252
 253    Returns the number of elements in *array*, or 0 if *array* is NULL
 254    or not a JSON array.
 255
 256 .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
 257
 258    .. refcounting:: borrow
 259
 260    Returns the element in *array* at position *index*. The valid range
 261    for *index* is from 0 to the return value of
 262    :cfunc:`json_array_size()` minus 1. If *array* is not a JSON array,
 263    if *array* is *NULL*, or if *index* is out of range, *NULL* is
 264    returned.
 265
 266 .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
 267
 268    Replaces the element in *array* at position *index* with *value*.
 269    The valid range for *index* is from 0 to the return value of
 270    :cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on
 271    error.
 272
 273 .. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
 274
 275    Like :cfunc:`json_array_set()` but steals the reference to *value*.
 276    This is useful when *value* is newly created and not used after
 277    the call.
 278
 279    .. versionadded:: 1.1
 280
 281 .. cfunction:: int json_array_append(json_t *array, json_t *value)
 282
 283    Appends *value* to the end of *array*, growing the size of *array*
 284    by 1. Returns 0 on success and -1 on error.
 285
 286 .. cfunction:: int json_array_append_new(json_t *array, json_t *value)
 287
 288    Like :cfunc:`json_array_append()` but steals the reference to
 289    *value*. This is useful when *value* is newly created and not used
 290    after the call.
 291
 292    .. versionadded:: 1.1
 293
 294 .. cfunction:: int json_array_insert(json_t *array, unsigned int index, json_t *value)
 295
 296    Inserts *value* to *array* at position *index*, shifting the
 297    elements at *index* and after it one position towards the end of
 298    the array. Returns 0 on success and -1 on error.
 299
 300    .. versionadded:: 1.1
 301
 302 .. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value)
 303
 304    Like :cfunc:`json_array_insert()` but steals the reference to
 305    *value*. This is useful when *value* is newly created and not used
 306    after the call.
 307
 308    .. versionadded:: 1.1
 309
 310 .. cfunction:: int json_array_remove(json_t *array, unsigned int index)
 311
 312    Removes the element in *array* at position *index*, shifting the
 313    elements after *index* one position towards the start of the array.
 314    Returns 0 on success and -1 on error.
 315
 316    .. versionadded:: 1.1
 317
 318 .. cfunction:: int json_array_clear(json_t *array)
 319
 320    Removes all elements from *array*. Returns 0 on sucess and -1 on
 321    error.
 322
 323    .. versionadded:: 1.1
 324
 325 .. cfunction:: int json_array_extend(json_t *array, json_t *other_array)
 326
 327    Appends all elements in *other_array* to the end of *array*.
 328    Returns 0 on success and -1 on error.
 329
 330    .. versionadded:: 1.1
 331
 332
 333 Object
 334 ======
 335
 336 A JSON object is a dictionary of key-value pairs, where the key is a
 337 Unicode string and the value is any JSON value.
 338
 339 .. cfunction:: json_t *json_object(void)
 340
 341    .. refcounting:: new
 342
 343    Returns a new JSON object, or *NULL* on error. Initially, the
 344    object is empty.
 345
 346 .. cfunction:: unsigned int json_object_size(const json_t *object)
 347
 348    Returns the number of elements in *object*, or 0 if *object* is not
 349    a JSON object.
 350
 351    .. versionadded:: 1.1
 352
 353 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 354
 355    .. refcounting:: borrow
 356
 357    Get a value corresponding to *key* from *object*. Returns *NULL* if
 358    *key* is not found and on error.
 359
 360 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 361
 362    Set the value of *key* to *value* in *object*. *key* must be a
 363    valid null terminated UTF-8 encoded Unicode string. If there
 364    already is a value for *key*, it is replaced by the new value.
 365    Returns 0 on success and -1 on error.
 366
 367 .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 368
 369    Like :cfunc:`json_object_set()` but steals the reference to
 370    *value*. This is useful when *value* is newly created and not used
 371    after the call.
 372
 373    .. versionadded:: 1.1
 374
 375 .. cfunction:: int json_object_del(json_t *object, const char *key)
 376
 377    Delete *key* from *object* if it exists. Returns 0 on success, or
 378    -1 if *key* was not found.
 379
 380
 381 .. cfunction:: int json_object_clear(json_t *object)
 382
 383    Remove all elements from *object*. Returns 0 on success and -1 if
 384    *object* is not a JSON object.
 385
 386    .. versionadded:: 1.1
 387
 388 .. cfunction:: int json_object_update(json_t *object, json_t *other)
 389
 390    Update *object* with the key-value pairs from *other*, overwriting
 391    existing keys. Returns 0 on success or -1 on error.
 392
 393    .. versionadded:: 1.1
 394
 395
 396 The following functions implement an iteration protocol for objects:
 397
 398 .. cfunction:: void *json_object_iter(json_t *object)
 399
 400    Returns an opaque iterator which can be used to iterate over all
 401    key-value pairs in *object*, or *NULL* if *object* is empty.
 402
 403 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 404
 405    Returns an iterator pointing to the next key-value pair in *object*
 406    after *iter*, or *NULL* if the whole object has been iterated
 407    through.
 408
 409 .. cfunction:: const char *json_object_iter_key(void *iter)
 410
 411    Extract the associated key from *iter*.
 412
 413 .. cfunction:: json_t *json_object_iter_value(void *iter)
 414
 415    .. refcounting:: borrow
 416
 417    Extract the associated value from *iter*.
 418
 419 The iteration protocol can be used for example as follows::
 420
 421    /* obj is a JSON object */
 422    const char *key;
 423    json_t *value;
 424    void *iter = json_object_iter(obj);
 425    while(iter)
 426    {
 427        key = json_object_iter_key(iter);
 428        value = json_object_iter_value(iter);
 429        /* use key and value ... */
 430        iter = json_object_iter_next(obj, iter);
 431    }
 432
 433
 434 Encoding
 435 ========
 436
 437 This sections describes the functions that can be used to encode
 438 values to JSON. Only objects and arrays can be encoded, since they are
 439 the only valid "root" values of a JSON text.
 440
 441 Each function takes a *flags* parameter that controls some aspects of
 442 how the data is encoded. Its default value is 0. The following macros
 443 can be ORed together to obtain *flags*.
 444
 445 ``JSON_INDENT(n)``
 446    Pretty-print the result, indenting arrays and objects by *n*
 447    spaces. The valid range for *n* is between 0 and 255, other values
 448    result in an undefined output. If ``JSON_INDENT`` is not used or
 449    *n* is 0, no pretty-printing is done and the result is a compact
 450    representation.
 451
 452 The following functions perform the actual JSON encoding. The result
 453 is in UTF-8.
 454
 455 .. cfunction:: char *json_dumps(const json_t *root, unsigned long flags)
 456
 457    Returns the JSON representation of *root* as a string, or *NULL* on
 458    error. *flags* is described above. The return value must be freed
 459    by the caller using :cfunc:`free()`.
 460
 461 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags)
 462
 463    Write the JSON representation of *root* to the stream *output*.
 464    *flags* is described above. Returns 0 on success and -1 on error.
 465
 466 .. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags)
 467
 468    Write the JSON representation of *root* to the file *path*. If
 469    *path* already exists, it is overwritten. *flags* is described
 470    above. Returns 0 on success and -1 on error.
 471
 472
 473 Decoding
 474 ========
 475
 476 This sections describes the functions that can be used to decode JSON
 477 text to the Jansson representation of JSON data. The JSON
 478 specification requires that a JSON text is either a serialized array
 479 or object, and this requirement is also enforced with the following
 480 functions.
 481
 482 The only supported character encoding is UTF-8 (which ASCII is a
 483 subset of).
 484
 485 .. ctype:: json_error_t
 486
 487    This data structure is used to return information on decoding
 488    errors from the decoding functions. Its definition is repeated
 489    here::
 490
 491       #define JSON_ERROR_TEXT_LENGTH  160
 492
 493       typedef struct {
 494           char text[JSON_ERROR_TEXT_LENGTH];
 495           int line;
 496       } json_error_t;
 497
 498    *line* is the line number on which the error occurred, or -1 if
 499    this information is not available. *text* contains the error
 500    message (in UTF-8), or an empty string if a message is not
 501    available.
 502
 503    The normal usef of :ctype:`json_error_t` is to allocate it normally
 504    on the stack, and pass a pointer to a decoding function. Example::
 505
 506       int main() {
 507           json_t *json;
 508           json_error_t error;
 509
 510           json = json_load_file("/path/to/file.json", &error);
 511           if(!json) {
 512               /* the error variable contains error information */
 513           }
 514           ...
 515       }
 516
 517    Also note that if the decoding succeeded (``json != NULL`` in the
 518    above example), the contents of ``error`` are unspecified.
 519
 520    All decoding functions also accept *NULL* as the
 521    :ctype:`json_error_t` pointer, in which case no error information
 522    is returned to the caller.
 523
 524 The following functions perform the actual JSON decoding.
 525
 526 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 527
 528    .. refcounting:: new
 529
 530    Decodes the JSON string *input* and returns the array or object it
 531    contains, or *NULL* on error, in which case *error* is filled with
 532    information about the error. See above for discussion on the
 533    *error* parameter.
 534
 535 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 536
 537    .. refcounting:: new
 538
 539    Decodes the JSON text in stream *input* and returns the array or
 540    object it contains, or *NULL* on error, in which case *error* is
 541    filled with information about the error. See above for discussion
 542    on the *error* parameter.
 543
 544 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 545
 546    .. refcounting:: new
 547
 548    Decodes the JSON text in file *path* and returns the array or
 549    object it contains, or *NULL* on error, in which case *error* is
 550    filled with information about the error. See above for discussion
 551    on the *error* parameter.