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.
 103
 104 .. cfunction:: json_is_number(const json_t *json)
 105
 106    Returns true for values of types :const:`JSON_INTEGER` and
 107    :const:`JSON_REAL`, and false for other types.
 108
 109 .. cfunction:: json_is_boolean(const json_t *json)
 110
 111    Returns true for types :const:`JSON_TRUE` and :const:`JSON_FALSE`,
 112    and false for values of other types.
 113
 114
 115 Reference Count
 116 ---------------
 117
 118 The reference count is used to track whether a value is still in use
 119 or not. When a value is created, it's reference count is set to 1. If
 120 a reference to a value is kept (e.g. a value is stored somewhere for
 121 later use), its reference count is incremented, and when the value is
 122 no longer needed, the reference count is decremented. When the
 123 reference count drops to zero, there are no references left, and the
 124 value can be destroyed.
 125
 126 The following functions are used to manipulate the reference count.
 127
 128 .. cfunction:: json_t *json_incref(json_t *json)
 129
 130    Increment the reference count of *json*. Returns *json*.
 131
 132 .. cfunction:: void json_decref(json_t *json)
 133
 134    Decrement the reference count of *json*. As soon as a call to
 135    :cfunc:`json_decref()` drops the reference count to zero, the value
 136    is destroyed and it can no longer be used.
 137
 138 Functions creating new JSON values set the reference count to 1. These
 139 functions are said to return a **new reference**. Other functions
 140 returning (existing) JSON values do not normally increase the
 141 reference count. These functions are said to return a **borrowed
 142 reference**. So, if the user will hold a reference to a value returned
 143 as a borrowed reference, he must call :cfunc:`json_incref`. As soon as
 144 the value is no longer needed, :cfunc:`json_decref` should be called
 145 to release the reference.
 146
 147 Normally, all functions accepting a JSON value as an argument will
 148 manage the reference, i.e. increase and decrease the reference count
 149 as needed. However, some functions **steal** the reference, i.e. they
 150 have the same result as if the user called :cfunc:`json_decref()` on
 151 the argument right after calling the function. These are usually
 152 convenience functions for adding new references to containers and not
 153 to worry about the reference count.
 154
 155 In the following sections it is clearly documented whether a function
 156 will return a new or borrowed reference or steal a reference to its
 157 argument.
 158
 159
 160 True, False and Null
 161 ====================
 162
 163 .. cfunction:: json_t *json_true(void)
 164
 165    .. refcounting:: new
 166
 167    Returns a value of the type :const:`JSON_TRUE`, or *NULL* on
 168    error.
 169
 170 .. cfunction:: json_t *json_false(void)
 171
 172    .. refcounting:: new
 173
 174    Returns a value of the type :const:`JSON_FALSE`, or *NULL* on
 175    error.
 176
 177 .. cfunction:: json_t *json_null(void)
 178
 179    .. refcounting:: new
 180
 181    Returns a value of the type :const:`JSON_NULL`, or *NULL* on
 182    error.
 183
 184
 185 String
 186 ======
 187
 188 .. cfunction:: json_t *json_string(const char *value)
 189
 190    .. refcounting:: new
 191
 192    Returns a new value of the type :const:`JSON_STRING`, or *NULL* on
 193    error. *value* must be a valid UTF-8 encoded Unicode string.
 194
 195 .. cfunction:: const char *json_string_value(const json_t *json)
 196
 197    Returns the associated value of a :const:`JSON_STRING` value as a
 198    null terminated UTF-8 encoded string.
 199
 200
 201 Number
 202 ======
 203
 204 .. cfunction:: json_t *json_integer(int value)
 205
 206    .. refcounting:: new
 207
 208    Returns a new value of the type :const:`JSON_INTEGER`, or *NULL* on
 209    error.
 210
 211 .. cfunction:: int json_integer_value(const json_t *json)
 212
 213    Returns the associated integer value of values of the type
 214    :const:`JSON_INTEGER`, or 0 for values of other types.
 215
 216 .. cfunction:: json_t *json_real(double value)
 217
 218    .. refcounting:: new
 219
 220    Returns a new value of the type :const:`JSON_REAL`, or *NULL* on
 221    error.
 222
 223 .. cfunction:: double json_real_value(const json_t *json)
 224
 225    Returns the associated real value of values of the type
 226    :const:`JSON_INTEGER`, or 0 for values of other types.
 227
 228 In addition to the functions above, there's a common query function
 229 for integers and reals:
 230
 231 .. cfunction:: double json_number_value(const json_t *json)
 232
 233    Returns the value of either ``JSON_INTEGER`` or ``JSON_REAL``, cast
 234    to double regardless of the actual type.
 235
 236
 237 Array
 238 =====
 239
 240 A JSON array is an ordered collection of other JSON values.
 241
 242 .. cfunction:: json_t *json_array(void)
 243
 244    .. refcounting:: new
 245
 246    Returns a new value of the type :const:`JSON_ARRAY`, or *NULL* on
 247    error. Initially, the array is empty.
 248
 249 .. cfunction:: unsigned int json_array_size(const json_t *array)
 250
 251    Returns the number of elements in *array*.
 252
 253 .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
 254
 255    .. refcounting:: borrow
 256
 257    Returns the element in *array* at position *index*, or *NULL* if
 258    *index* is out of range. The valid range for *index* is from 0 to
 259    the return value of :cfunc:`json_array_size()` minus 1.
 260
 261 .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
 262
 263    Replaces the element in *array* at position *index* with *value*.
 264    Returns 0 on success, or -1 if *index* is out of range. The valid
 265    range for *index* is from 0 to the return value of
 266    :cfunc:`json_array_size()` minus 1.
 267
 268 .. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
 269
 270    Like :cfunc:`json_array_set()` but steals the reference to *value*.
 271    This is useful when *value* is newly created and not used after
 272    the call.
 273
 274    .. versionadded:: 1.1
 275
 276 .. cfunction:: int json_array_append(json_t *array, json_t *value)
 277
 278    Appends *value* to the end of *array*, growing the size of *array*
 279    by 1. Returns 0 on success and -1 on error.
 280
 281 .. cfunction:: int json_array_append_new(json_t *array, json_t *value)
 282
 283    Like :cfunc:`json_array_append()` but steals the reference to
 284    *value*. This is useful when *value* is newly created and not used
 285    after the call.
 286
 287    .. versionadded:: 1.1
 288
 289
 290 Object
 291 ======
 292
 293 A JSON object is a dictionary of key-value pairs, where the key is a
 294 Unicode string and the value is any JSON value.
 295
 296 .. cfunction:: json_t *json_object(void)
 297
 298    .. refcounting:: new
 299
 300    Returns a new value of the type :const:`JSON_OBJECT`, or *NULL* on
 301    error. Initially, the object is empty.
 302
 303 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 304
 305    .. refcounting:: borrow
 306
 307    Get a value corresponding to *key* from *object*. Returns *NULL* if
 308    *key* is not found and on error.
 309
 310 .. cfunction:: int json_object_set(json_t *object, const char *key, json_t *value)
 311
 312    Set the value of *key* to *value* in *object*. *key* must be a
 313    valid null terminated UTF-8 encoded Unicode string. If there
 314    already is a value for *key*, it is replaced by the new value.
 315    Returns 0 on success and -1 on error.
 316
 317 .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 318
 319    Like :cfunc:`json_object_set()` but steals the reference to
 320    *value*. This is useful when *value* is newly created and not used
 321    after the call.
 322
 323    .. versionadded:: 1.1
 324
 325 .. cfunction:: int json_object_del(json_t *object, const char *key)
 326
 327    Delete *key* from *object* if it exists. Returns 0 on success, or
 328    -1 if *key* was not found.
 329
 330
 331 The following functions implement an iteration protocol for objects:
 332
 333 .. cfunction:: void *json_object_iter(json_t *object)
 334
 335    Returns an opaque iterator which can be used to iterate over all
 336    key-value pairs in *object*, or *NULL* if *object* is empty.
 337
 338 .. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
 339
 340    Returns an iterator pointing to the next key-value pair in *object*
 341    after *iter*, or *NULL* if the whole object has been iterated
 342    through.
 343
 344 .. cfunction:: const char *json_object_iter_key(void *iter)
 345
 346    Extract the associated key from *iter*.
 347
 348 .. cfunction:: json_t *json_object_iter_value(void *iter)
 349
 350    .. refcounting:: borrow
 351
 352    Extract the associated value from *iter*.
 353
 354
 355 Encoding
 356 ========
 357
 358 This sections describes the functions that can be used to encode
 359 values to JSON. Only objects and arrays can be encoded, since they are
 360 the only valid "root" values of a JSON text.
 361
 362 Each function takes a *flags* parameter that controls some aspects of
 363 how the data is encoded. Its default value is 0. The following macros
 364 can be ORed together to obtain *flags*.
 365
 366 ``JSON_INDENT(n)``
 367    Pretty-print the result, indenting arrays and objects by *n*
 368    spaces. The valid range for *n* is between 0 and 255, other values
 369    result in an undefined output. If ``JSON_INDENT`` is not used or
 370    *n* is 0, no pretty-printing is done and the result is a compact
 371    representation.
 372
 373 The following functions perform the actual JSON encoding. The result
 374 is in UTF-8.
 375
 376 .. cfunction:: char *json_dumps(const json_t *root, uint32_t flags)
 377
 378    Returns the JSON representation of *root* as a string, or *NULL* on
 379    error. *flags* is described above. The return value must be freed
 380    by the caller using :cfunc:`free()`.
 381
 382 .. cfunction:: int json_dumpf(const json_t *root, FILE *output, uint32_t flags)
 383
 384    Write the JSON representation of *root* to the stream *output*.
 385    *flags* is described above. Returns 0 on success and -1 on error.
 386
 387 .. cfunction:: int json_dump_file(const json_t *json, const char *path, uint32_t flags)
 388
 389    Write the JSON representation of *root* to the file *path*. If
 390    *path* already exists, it is overwritten. *flags* is described
 391    above. Returns 0 on success and -1 on error.
 392
 393
 394 Decoding
 395 ========
 396
 397 This sections describes the functions that can be used to decode JSON
 398 text to the Jansson representation of JSON data. The JSON
 399 specification requires that a JSON text is either a serialized array
 400 or object, and this requirement is also enforced with the following
 401 functions.
 402
 403 The only supported character encoding is UTF-8 (which ASCII is a
 404 subset of).
 405
 406 .. ctype:: json_error_t
 407
 408    This data structure is used to return information on decoding
 409    errors from the decoding functions. Its definition is repeated
 410    here::
 411
 412       #define JSON_ERROR_TEXT_LENGTH  160
 413
 414       typedef struct {
 415           char text[JSON_ERROR_TEXT_LENGTH];
 416           int line;
 417       } json_error_t;
 418
 419    *line* is the line number on which the error occurred, or -1 if
 420    this information is not available. *text* contains the error
 421    message (in UTF-8), or an empty string if a message is not
 422    available.
 423
 424    The normal usef of :ctype:`json_error_t` is to allocate it normally
 425    on the stack, and pass a pointer to a decoding function. Example::
 426
 427       int main() {
 428           json_t *json;
 429           json_error_t error;
 430
 431           json = json_load_file("/path/to/file.json", &error);
 432           if(!json) {
 433               /* the error variable contains error information */
 434           }
 435           ...
 436       }
 437
 438    Also note that if the decoding succeeded (``json != NULL`` in the
 439    above example), the contents of ``error`` are unspecified.
 440
 441    All decoding functions also accept *NULL* as the
 442    :ctype:`json_error_t` pointer, in which case no error information
 443    is returned to the caller.
 444
 445 The following functions perform the actual JSON decoding.
 446
 447 .. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
 448
 449    .. refcounting:: new
 450
 451    Decodes the JSON string *input* and returns the array or object it
 452    contains, or *NULL* on error, in which case *error* is filled with
 453    information about the error. See above for discussion on the
 454    *error* parameter.
 455
 456 .. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
 457
 458    .. refcounting:: new
 459
 460    Decodes the JSON text in stream *input* and returns the array or
 461    object it contains, or *NULL* on error, in which case *error* is
 462    filled with information about the error. See above for discussion
 463    on the *error* parameter.
 464
 465 .. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
 466
 467    .. refcounting:: new
 468
 469    Decodes the JSON text in file *path* and returns the array or
 470    object it contains, or *NULL* on error, in which case *error* is
 471    filled with information about the error. See above for discussion
 472    on the *error* parameter.