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