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 *string)
 198
 199    Returns the associated value of *string* as a null terminated UTF-8
 200    encoded string, or *NULL* if *string* is not a JSON string.
 201
 202 .. cfunction:: int json_string_set(const json_t *string, const char *value)
 203
 204    Sets the associated value of *string* to *value*. *value* must be a
 205    valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
 206    error.
 207
 208    .. versionadded:: 1.1
 209
 210
 211 Number
 212 ======
 213
 214 .. cfunction:: json_t *json_integer(int value)
 215
 216    .. refcounting:: new
 217
 218    Returns a new JSON integer, or *NULL* on error.
 219
 220 .. cfunction:: int json_integer_value(const json_t *integer)
 221
 222    Returns the associated value of *integer*, or 0 if *json* is not a
 223    JSON integer.
 224
 225 .. cfunction:: int json_integer_set(const json_t *integer, int value)
 226
 227    Sets the associated value of *integer* to *value*. Returns 0 on
 228    success and -1 if *integer* is not a JSON integer.
 229
 230    .. versionadded:: 1.1
 231
 232 .. cfunction:: json_t *json_real(double value)
 233
 234    .. refcounting:: new
 235
 236    Returns a new JSON real, or *NULL* on error.
 237
 238 .. cfunction:: double json_real_value(const json_t *real)
 239
 240    Returns the associated value of *real*, or 0.0 if *real* is not a
 241    JSON real.
 242
 243 .. cfunction:: int json_real_set(const json_t *real, double value)
 244
 245    Sets the associated value of *real* to *value*. Returns 0 on
 246    success and -1 if *real* is not a JSON real.
 247
 248    .. versionadded:: 1.1
 249
 250 In addition to the functions above, there's a common query function
 251 for integers and reals:
 252
 253 .. cfunction:: double json_number_value(const json_t *json)
 254
 255    Returns the associated value of the JSON integer or JSON real
 256    *json*, cast to double regardless of the actual type. If *json* is
 257    neither JSON real nor JSON integer, 0.0 is returned.
 258
 259
 260 Array
 261 =====
 262
 263 A JSON array is an ordered collection of other JSON values.
 264
 265 .. cfunction:: json_t *json_array(void)
 266
 267    .. refcounting:: new
 268
 269    Returns a new JSON array, or *NULL* on error. Initially, the array
 270    is empty.
 271
 272 .. cfunction:: unsigned int json_array_size(const json_t *array)
 273
 274    Returns the number of elements in *array*, or 0 if *array* is NULL
 275    or not a JSON array.
 276
 277 .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
 278
 279    .. refcounting:: borrow
 280
 281    Returns the element in *array* at position *index*. The valid range
 282    for *index* is from 0 to the return value of
 283    :cfunc:`json_array_size()` minus 1. If *array* is not a JSON array,
 284    if *array* is *NULL*, or if *index* is out of range, *NULL* is
 285    returned.
 286
 287 .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
 288
 289    Replaces the element in *array* at position *index* with *value*.
 290    The valid range for *index* is from 0 to the return value of
 291    :cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on
 292    error.
 293
 294 .. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
 295
 296    Like :cfunc:`json_array_set()` but steals the reference to *value*.
 297    This is useful when *value* is newly created and not used after
 298    the call.
 299
 300    .. versionadded:: 1.1
 301
 302 .. cfunction:: int json_array_append(json_t *array, json_t *value)
 303
 304    Appends *value* to the end of *array*, growing the size of *array*
 305    by 1. Returns 0 on success and -1 on error.
 306
 307 .. cfunction:: int json_array_append_new(json_t *array, json_t *value)
 308
 309    Like :cfunc:`json_array_append()` but steals the reference to
 310    *value*. This is useful when *value* is newly created and not used
 311    after the call.
 312
 313    .. versionadded:: 1.1
 314
 315 .. cfunction:: int json_array_insert(json_t *array, unsigned int index, json_t *value)
 316
 317    Inserts *value* to *array* at position *index*, shifting the
 318    elements at *index* and after it one position towards the end of
 319    the array. Returns 0 on success and -1 on error.
 320
 321    .. versionadded:: 1.1
 322
 323 .. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value)
 324
 325    Like :cfunc:`json_array_insert()` but steals the reference to
 326    *value*. This is useful when *value* is newly created and not used
 327    after the call.
 328
 329    .. versionadded:: 1.1
 330
 331 .. cfunction:: int json_array_remove(json_t *array, unsigned int index)
 332
 333    Removes the element in *array* at position *index*, shifting the
 334    elements after *index* one position towards the start of the array.
 335    Returns 0 on success and -1 on error.
 336
 337    .. versionadded:: 1.1
 338
 339 .. cfunction:: int json_array_clear(json_t *array)
 340
 341    Removes all elements from *array*. Returns 0 on sucess and -1 on
 342    error.
 343
 344    .. versionadded:: 1.1
 345
 346 .. cfunction:: int json_array_extend(json_t *array, json_t *other_array)
 347
 348    Appends all elements in *other_array* to the end of *array*.
 349    Returns 0 on success and -1 on error.
 350
 351    .. versionadded:: 1.1
 352
 353
 354 Object
 355 ======
 356
 357 A JSON object is a dictionary of key-value pairs, where the key is a
 358 Unicode string and the value is any JSON value.
 359
 360 .. cfunction:: json_t *json_object(void)
 361
 362    .. refcounting:: new
 363
 364    Returns a new JSON object, or *NULL* on error. Initially, the
 365    object is empty.
 366
 367 .. cfunction:: unsigned int json_object_size(const json_t *object)
 368
 369    Returns the number of elements in *object*, or 0 if *object* is not
 370    a JSON object.
 371
 372    .. versionadded:: 1.1
 373
 374 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 375
 376    .. refcounting:: borrow
 377
 378    Get a value corresponding to *key* from *object*. Returns *NULL* if
 379    *key* is not found and on error.
 380
 381 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 382
 383    Set the value of *key* to *value* in *object*. *key* must be a
 384    valid null terminated UTF-8 encoded Unicode string. If there
 385    already is a value for *key*, it is replaced by the new value.
 386    Returns 0 on success and -1 on error.
 387
 388 .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 389
 390    Like :cfunc:`json_object_set()` but steals the reference to
 391    *value*. This is useful when *value* is newly created and not used
 392    after the call.
 393
 394    .. versionadded:: 1.1
 395
 396 .. cfunction:: int json_object_del(json_t *object, const char *key)
 397
 398    Delete *key* from *object* if it exists. Returns 0 on success, or
 399    -1 if *key* was not found.
 400
 401
 402 .. cfunction:: int json_object_clear(json_t *object)
 403
 404    Remove all elements from *object*. Returns 0 on success and -1 if
 405    *object* is not a JSON object.
 406
 407    .. versionadded:: 1.1
 408
 409 .. cfunction:: int json_object_update(json_t *object, json_t *other)
 410
 411    Update *object* with the key-value pairs from *other*, overwriting
 412    existing keys. Returns 0 on success or -1 on error.
 413
 414    .. versionadded:: 1.1
 415
 416
 417 The following functions implement an iteration protocol for objects:
 418
 419 .. cfunction:: void *json_object_iter(json_t *object)
 420
 421    Returns an opaque iterator which can be used to iterate over all
 422    key-value pairs in *object*, or *NULL* if *object* is empty.
 423
 424 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 425
 426    Returns an iterator pointing to the next key-value pair in *object*
 427    after *iter*, or *NULL* if the whole object has been iterated
 428    through.
 429
 430 .. cfunction:: const char *json_object_iter_key(void *iter)
 431
 432    Extract the associated key from *iter*.
 433
 434 .. cfunction:: json_t *json_object_iter_value(void *iter)
 435
 436    .. refcounting:: borrow
 437
 438    Extract the associated value from *iter*.
 439
 440 The iteration protocol can be used for example as follows::
 441
 442    /* obj is a JSON object */
 443    const char *key;
 444    json_t *value;
 445    void *iter = json_object_iter(obj);
 446    while(iter)
 447    {
 448        key = json_object_iter_key(iter);
 449        value = json_object_iter_value(iter);
 450        /* use key and value ... */
 451        iter = json_object_iter_next(obj, iter);
 452    }
 453
 454
 455 Encoding
 456 ========
 457
 458 This sections describes the functions that can be used to encode
 459 values to JSON. Only objects and arrays can be encoded, since they are
 460 the only valid "root" values of a JSON text.
 461
 462 Each function takes a *flags* parameter that controls some aspects of
 463 how the data is encoded. Its default value is 0. The following macros
 464 can be ORed together to obtain *flags*.
 465
 466 ``JSON_INDENT(n)``
 467    Pretty-print the result, indenting arrays and objects by *n*
 468    spaces. The valid range for *n* is between 0 and 255, other values
 469    result in an undefined output. If ``JSON_INDENT`` is not used or
 470    *n* is 0, no pretty-printing is done and the result is a compact
 471    representation.
 472
 473 The following functions perform the actual JSON encoding. The result
 474 is in UTF-8.
 475
 476 .. cfunction:: char *json_dumps(const json_t *root, unsigned long flags)
 477
 478    Returns the JSON representation of *root* as a string, or *NULL* on
 479    error. *flags* is described above. The return value must be freed
 480    by the caller using :cfunc:`free()`.
 481
 482 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags)
 483
 484    Write the JSON representation of *root* to the stream *output*.
 485    *flags* is described above. Returns 0 on success and -1 on error.
 486
 487 .. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags)
 488
 489    Write the JSON representation of *root* to the file *path*. If
 490    *path* already exists, it is overwritten. *flags* is described
 491    above. Returns 0 on success and -1 on error.
 492
 493
 494 Decoding
 495 ========
 496
 497 This sections describes the functions that can be used to decode JSON
 498 text to the Jansson representation of JSON data. The JSON
 499 specification requires that a JSON text is either a serialized array
 500 or object, and this requirement is also enforced with the following
 501 functions.
 502
 503 The only supported character encoding is UTF-8 (which ASCII is a
 504 subset of).
 505
 506 .. ctype:: json_error_t
 507
 508    This data structure is used to return information on decoding
 509    errors from the decoding functions. Its definition is repeated
 510    here::
 511
 512       #define JSON_ERROR_TEXT_LENGTH  160
 513
 514       typedef struct {
 515           char text[JSON_ERROR_TEXT_LENGTH];
 516           int line;
 517       } json_error_t;
 518
 519    *line* is the line number on which the error occurred, or -1 if
 520    this information is not available. *text* contains the error
 521    message (in UTF-8), or an empty string if a message is not
 522    available.
 523
 524    The normal usef of :ctype:`json_error_t` is to allocate it normally
 525    on the stack, and pass a pointer to a decoding function. Example::
 526
 527       int main() {
 528           json_t *json;
 529           json_error_t error;
 530
 531           json = json_load_file("/path/to/file.json", &error);
 532           if(!json) {
 533               /* the error variable contains error information */
 534           }
 535           ...
 536       }
 537
 538    Also note that if the decoding succeeded (``json != NULL`` in the
 539    above example), the contents of ``error`` are unspecified.
 540
 541    All decoding functions also accept *NULL* as the
 542    :ctype:`json_error_t` pointer, in which case no error information
 543    is returned to the caller.
 544
 545 The following functions perform the actual JSON decoding.
 546
 547 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 548
 549    .. refcounting:: new
 550
 551    Decodes the JSON string *input* and returns the array or object it
 552    contains, or *NULL* on error, in which case *error* is filled with
 553    information about the error. See above for discussion on the
 554    *error* parameter.
 555
 556 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 557
 558    .. refcounting:: new
 559
 560    Decodes the JSON text in stream *input* and returns the array or
 561    object it contains, or *NULL* on error, in which case *error* is
 562    filled with information about the error. See above for discussion
 563    on the *error* parameter.
 564
 565 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 566
 567    .. refcounting:: new
 568
 569    Decodes the JSON text in file *path* and returns the array or
 570    object it contains, or *NULL* on error, in which case *error* is
 571    filled with information about the error. See above for discussion
 572    on the *error* parameter.