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*. Returns *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_set_new(json_t *array, unsigned int index, json_t *value)
 263
 264    Like :cfunc:`json_array_set()` but steals the reference to *value*.
 265    This is useful when *value* is newly created and not used after
 266    the call.
 267
 268    .. versionadded:: 1.1
 269
 270 .. cfunction:: int json_array_append(json_t *array, json_t *value)
 271
 272    Appends *value* to the end of *array*, growing the size of *array*
 273    by 1. Returns 0 on success and -1 on error.
 274
 275 .. cfunction:: int json_array_append_new(json_t *array, json_t *value)
 276
 277    Like :cfunc:`json_array_append()` but steals the reference to
 278    *value*. This is useful when *value* is newly created and not used
 279    after the call.
 280
 281    .. versionadded:: 1.1
 282
 283
 284 Object
 285 ======
 286
 287 A JSON object is a dictionary of key-value pairs, where the key is a
 288 Unicode string and the value is any JSON value.
 289
 290 .. cfunction:: json_t *json_object(void)
 291
 292    .. refcounting:: new
 293
 294    Returns a new value of the type :const:`JSON_OBJECT`, or *NULL* on
 295    error. Initially, the object is empty.
 296
 297 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 298
 299    .. refcounting:: borrow
 300
 301    Get a value corresponding to *key* from *object*. Returns *NULL* if
 302    *key* is not found and on error.
 303
 304 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 305
 306    Set the value of *key* to *value* in *object*. *key* must be a
 307    valid null terminated UTF-8 encoded Unicode string. If there
 308    already is a value for *key*, it is replaced by the new value.
 309    Returns 0 on success and -1 on error.
 310
 311 .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 312
 313    Like :cfunc:`json_object_set()` but steals the reference to
 314    *value*. This is useful when *value* is newly created and not used
 315    after the call.
 316
 317    .. versionadded:: 1.1
 318
 319 .. cfunction:: int json_object_del(json_t *object, const char *key)
 320
 321    Delete *key* from *object* if it exists. Returns 0 on success, or
 322    -1 if *key* was not found.
 323
 324
 325 The following functions implement an iteration protocol for objects:
 326
 327 .. cfunction:: void *json_object_iter(json_t *object)
 328
 329    Returns an opaque iterator which can be used to iterate over all
 330    key-value pairs in *object*, or *NULL* if *object* is empty.
 331
 332 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 333
 334    Returns an iterator pointing to the next key-value pair in *object*
 335    after *iter*, or *NULL* if the whole object has been iterated
 336    through.
 337
 338 .. cfunction:: const char *json_object_iter_key(void *iter)
 339
 340    Extract the associated key from *iter*.
 341
 342 .. cfunction:: json_t *json_object_iter_value(void *iter)
 343
 344    .. refcounting:: borrow
 345
 346    Extract the associated value from *iter*.
 347
 348
 349 Encoding
 350 ========
 351
 352 This sections describes the functions that can be used to encode
 353 values to JSON. Only objects and arrays can be encoded, since they are
 354 the only valid "root" values of a JSON text.
 355
 356 Each function takes a *flags* parameter that controls some aspects of
 357 how the data is encoded. Its default value is 0. The following macros
 358 can be ORed together to obtain *flags*.
 359
 360 ``JSON_INDENT(n)``
 361    Pretty-print the result, indenting arrays and objects by *n*
 362    spaces. The valid range for *n* is between 0 and 255, other values
 363    result in an undefined output. If ``JSON_INDENT`` is not used or
 364    *n* is 0, no pretty-printing is done and the result is a compact
 365    representation.
 366
 367 The following functions perform the actual JSON encoding. The result
 368 is in UTF-8.
 369
 370 .. cfunction:: char *json_dumps(const json_t *root, uint32_t flags)
 371
 372    Returns the JSON representation of *root* as a string, or *NULL* on
 373    error. *flags* is described above. The return value must be freed
 374    by the caller using :cfunc:`free()`.
 375
 376 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, uint32_t flags)
 377
 378    Write the JSON representation of *root* to the stream *output*.
 379    *flags* is described above. Returns 0 on success and -1 on error.
 380
 381 .. cfunction:: int json_dump_file(const json_t *json, const char *path, uint32_t flags)
 382
 383    Write the JSON representation of *root* to the file *path*. If
 384    *path* already exists, it is overwritten. *flags* is described
 385    above. Returns 0 on success and -1 on error.
 386
 387
 388 Decoding
 389 ========
 390
 391 This sections describes the functions that can be used to decode JSON
 392 text to the Jansson representation of JSON data. The JSON
 393 specification requires that a JSON text is either a serialized array
 394 or object, and this requirement is also enforced with the following
 395 functions.
 396
 397 The only supported character encoding is UTF-8 (which ASCII is a
 398 subset of).
 399
 400 .. ctype:: json_error_t
 401
 402    This data structure is used to return information on decoding
 403    errors from the decoding functions. Its definition is repeated
 404    here::
 405
 406       #define JSON_ERROR_TEXT_LENGTH  160
 407
 408       typedef struct {
 409           char text[JSON_ERROR_TEXT_LENGTH];
 410           int line;
 411       } json_error_t;
 412
 413    *line* is the line number on which the error occurred, or -1 if
 414    this information is not available. *text* contains the error
 415    message (in UTF-8), or an empty string if a message is not
 416    available.
 417
 418    The normal usef of :ctype:`json_error_t` is to allocate it normally
 419    on the stack, and pass a pointer to a decoding function. Example::
 420
 421       int main() {
 422           json_t *json;
 423           json_error_t error;
 424
 425           json = json_load_file("/path/to/file.json", &error);
 426           if(!json) {
 427               /* the error variable contains error information */
 428           }
 429           ...
 430       }
 431
 432    Also note that if the decoding succeeded (``json != NULL`` in the
 433    above example), the contents of ``error`` are unspecified.
 434
 435    All decoding functions also accept *NULL* as the
 436    :ctype:`json_error_t` pointer, in which case no error information
 437    is returned to the caller.
 438
 439 The following functions perform the actual JSON decoding.
 440
 441 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 442
 443    .. refcounting:: new
 444
 445    Decodes the JSON string *input* and returns the array or object it
 446    contains, or *NULL* on error, in which case *error* is filled with
 447    information about the error. See above for discussion on the
 448    *error* parameter.
 449
 450 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 451
 452    .. refcounting:: new
 453
 454    Decodes the JSON text in stream *input* and returns the array or
 455    object it contains, or *NULL* on error, in which case *error* is
 456    filled with information about the error. See above for discussion
 457    on the *error* parameter.
 458
 459 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 460
 461    .. refcounting:: new
 462
 463    Decodes the JSON text in file *path* and returns the array or
 464    object it contains, or *NULL* on error, in which case *error* is
 465    filled with information about the error. See above for discussion
 466    on the *error* parameter.