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:: json_t *json_object_get(const json_t *object, const char *key)
 347
 348    .. refcounting:: borrow
 349
 350    Get a value corresponding to *key* from *object*. Returns *NULL* if
 351    *key* is not found and on error.
 352
 353 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 354
 355    Set the value of *key* to *value* in *object*. *key* must be a
 356    valid null terminated UTF-8 encoded Unicode string. If there
 357    already is a value for *key*, it is replaced by the new value.
 358    Returns 0 on success and -1 on error.
 359
 360 .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 361
 362    Like :cfunc:`json_object_set()` but steals the reference to
 363    *value*. This is useful when *value* is newly created and not used
 364    after the call.
 365
 366    .. versionadded:: 1.1
 367
 368 .. cfunction:: int json_object_del(json_t *object, const char *key)
 369
 370    Delete *key* from *object* if it exists. Returns 0 on success, or
 371    -1 if *key* was not found.
 372
 373
 374 The following functions implement an iteration protocol for objects:
 375
 376 .. cfunction:: void *json_object_iter(json_t *object)
 377
 378    Returns an opaque iterator which can be used to iterate over all
 379    key-value pairs in *object*, or *NULL* if *object* is empty.
 380
 381 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 382
 383    Returns an iterator pointing to the next key-value pair in *object*
 384    after *iter*, or *NULL* if the whole object has been iterated
 385    through.
 386
 387 .. cfunction:: const char *json_object_iter_key(void *iter)
 388
 389    Extract the associated key from *iter*.
 390
 391 .. cfunction:: json_t *json_object_iter_value(void *iter)
 392
 393    .. refcounting:: borrow
 394
 395    Extract the associated value from *iter*.
 396
 397 The iteration protocol can be used for example as follows::
 398
 399    /* obj is a JSON object */
 400    const char *key;
 401    json_t *value;
 402    void *iter = json_object_iter(obj);
 403    while(iter)
 404    {
 405        key = json_object_iter_key(iter);
 406        value = json_object_iter_value(iter);
 407        /* use key and value ... */
 408        iter = json_object_iter_next(obj, iter);
 409    }
 410
 411
 412 Encoding
 413 ========
 414
 415 This sections describes the functions that can be used to encode
 416 values to JSON. Only objects and arrays can be encoded, since they are
 417 the only valid "root" values of a JSON text.
 418
 419 Each function takes a *flags* parameter that controls some aspects of
 420 how the data is encoded. Its default value is 0. The following macros
 421 can be ORed together to obtain *flags*.
 422
 423 ``JSON_INDENT(n)``
 424    Pretty-print the result, indenting arrays and objects by *n*
 425    spaces. The valid range for *n* is between 0 and 255, other values
 426    result in an undefined output. If ``JSON_INDENT`` is not used or
 427    *n* is 0, no pretty-printing is done and the result is a compact
 428    representation.
 429
 430 The following functions perform the actual JSON encoding. The result
 431 is in UTF-8.
 432
 433 .. cfunction:: char *json_dumps(const json_t *root, unsigned long flags)
 434
 435    Returns the JSON representation of *root* as a string, or *NULL* on
 436    error. *flags* is described above. The return value must be freed
 437    by the caller using :cfunc:`free()`.
 438
 439 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags)
 440
 441    Write the JSON representation of *root* to the stream *output*.
 442    *flags* is described above. Returns 0 on success and -1 on error.
 443
 444 .. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags)
 445
 446    Write the JSON representation of *root* to the file *path*. If
 447    *path* already exists, it is overwritten. *flags* is described
 448    above. Returns 0 on success and -1 on error.
 449
 450
 451 Decoding
 452 ========
 453
 454 This sections describes the functions that can be used to decode JSON
 455 text to the Jansson representation of JSON data. The JSON
 456 specification requires that a JSON text is either a serialized array
 457 or object, and this requirement is also enforced with the following
 458 functions.
 459
 460 The only supported character encoding is UTF-8 (which ASCII is a
 461 subset of).
 462
 463 .. ctype:: json_error_t
 464
 465    This data structure is used to return information on decoding
 466    errors from the decoding functions. Its definition is repeated
 467    here::
 468
 469       #define JSON_ERROR_TEXT_LENGTH  160
 470
 471       typedef struct {
 472           char text[JSON_ERROR_TEXT_LENGTH];
 473           int line;
 474       } json_error_t;
 475
 476    *line* is the line number on which the error occurred, or -1 if
 477    this information is not available. *text* contains the error
 478    message (in UTF-8), or an empty string if a message is not
 479    available.
 480
 481    The normal usef of :ctype:`json_error_t` is to allocate it normally
 482    on the stack, and pass a pointer to a decoding function. Example::
 483
 484       int main() {
 485           json_t *json;
 486           json_error_t error;
 487
 488           json = json_load_file("/path/to/file.json", &error);
 489           if(!json) {
 490               /* the error variable contains error information */
 491           }
 492           ...
 493       }
 494
 495    Also note that if the decoding succeeded (``json != NULL`` in the
 496    above example), the contents of ``error`` are unspecified.
 497
 498    All decoding functions also accept *NULL* as the
 499    :ctype:`json_error_t` pointer, in which case no error information
 500    is returned to the caller.
 501
 502 The following functions perform the actual JSON decoding.
 503
 504 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 505
 506    .. refcounting:: new
 507
 508    Decodes the JSON string *input* and returns the array or object it
 509    contains, or *NULL* on error, in which case *error* is filled with
 510    information about the error. See above for discussion on the
 511    *error* parameter.
 512
 513 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 514
 515    .. refcounting:: new
 516
 517    Decodes the JSON text in stream *input* and returns the array or
 518    object it contains, or *NULL* on error, in which case *error* is
 519    filled with information about the error. See above for discussion
 520    on the *error* parameter.
 521
 522 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 523
 524    .. refcounting:: new
 525
 526    Decodes the JSON text in file *path* and returns the array or
 527    object it contains, or *NULL* on error, in which case *error* is
 528    filled with information about the error. See above for discussion
 529    on the *error* parameter.