X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fapiref.rst;h=f65dc5d809183c0a093c410cc079e9f92893682b;hb=fa268b50177c85776023e369ae4fb954bd076f6a;hp=397f4187142cfe71015075ed1fd279bd3cbb701a;hpb=8567816542e23860ca7d162e1da319e71b6d4f69;p=profile%2Fivi%2Fjansson.git diff --git a/doc/apiref.rst b/doc/apiref.rst index 397f418..f65dc5d 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -17,9 +17,46 @@ All declarations are in :file:`jansson.h`, so it's enough to in each source file. -All constants are prefixed ``JSON_`` and other identifiers with -``json_``. Type names are suffixed with ``_t`` and ``typedef``\ 'd so -that the ``struct`` keyword need not be used. +All constants are prefixed with ``JSON_`` (except for those describing +the library version, prefixed with ``JANSSON_``). Other identifiers +are prefixed with ``json_``. Type names are suffixed with ``_t`` and +``typedef``\ 'd so that the ``struct`` keyword need not be used. + + +Library Version +=============== + +The Jansson version is of the form *A.B.C*, where *A* is the major +version, *B* is the minor version and *C* is the micro version. If the +micro version is zero, it's omitted from the version string, i.e. the +version string is just *A.B*. + +When a new release only fixes bugs and doesn't add new features or +functionality, the micro version is incremented. When new features are +added in a backwards compatible way, the minor version is incremented +and the micro version is set to zero. When there are backwards +incompatible changes, the major version is incremented and others are +set to zero. + +The following preprocessor constants specify the current version of +the library: + +``JANSSON_VERSION_MAJOR``, ``JANSSON_VERSION_MINOR``, ``JANSSON_VERSION_MICRO`` + Integers specifying the major, minor and micro versions, + respectively. + +``JANSSON_VERSION`` + A string representation of the current version, e.g. ``"1.2.1"`` or + ``"1.3"``. + +``JANSSON_VERSION_HEX`` + A 3-byte hexadecimal representation of the version, e.g. + ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3. + This is useful in numeric comparisions, e.g.:: + + #if JANSSON_VERSION_HEX >= 0x010300 + /* Code specific to version 1.3 and above */ + #endif Value Representation @@ -264,21 +301,21 @@ U+10FFFF are allowed. UTF-8. Use this function only if you are certain that this really is the case (e.g. you have already checked it by other means). - .. versionadded:: 1.2 - .. function:: const char *json_string_value(const json_t *string) Returns the associated value of *string* as a null terminated UTF-8 encoded string, or *NULL* if *string* is not a JSON string. + The retuned value is read-only and must not be modified or freed by + the user. It is valid as long as *string* exists, i.e. as long as + its reference count has not dropped to zero. + .. function:: int json_string_set(const json_t *string, const char *value) Sets the associated value of *string* to *value*. *value* must be a valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on error. - .. versionadded:: 1.1 - .. function:: int json_string_set_nocheck(const json_t *string, const char *value) Like :func:`json_string_set`, but doesn't check that *value* is @@ -286,8 +323,6 @@ U+10FFFF are allowed. really is the case (e.g. you have already checked it by other means). - .. versionadded:: 1.2 - Number ====== @@ -353,8 +388,6 @@ information, see :ref:`rfc-conformance`. Sets the associated value of *integer* to *value*. Returns 0 on success and -1 if *integer* is not a JSON integer. - .. versionadded:: 1.1 - .. function:: json_t *json_real(double value) .. refcounting:: new @@ -371,8 +404,6 @@ information, see :ref:`rfc-conformance`. Sets the associated value of *real* to *value*. Returns 0 on success and -1 if *real* is not a JSON real. - .. versionadded:: 1.1 - In addition to the functions above, there's a common query function for integers and reals: @@ -423,8 +454,6 @@ A JSON array is an ordered collection of other JSON values. This is useful when *value* is newly created and not used after the call. - .. versionadded:: 1.1 - .. function:: int json_array_append(json_t *array, json_t *value) Appends *value* to the end of *array*, growing the size of *array* @@ -436,46 +465,35 @@ A JSON array is an ordered collection of other JSON values. *value*. This is useful when *value* is newly created and not used after the call. - .. versionadded:: 1.1 - .. function:: int json_array_insert(json_t *array, size_t index, json_t *value) Inserts *value* to *array* at position *index*, shifting the elements at *index* and after it one position towards the end of the array. Returns 0 on success and -1 on error. - .. versionadded:: 1.1 - .. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value) Like :func:`json_array_insert()` but steals the reference to *value*. This is useful when *value* is newly created and not used after the call. - .. versionadded:: 1.1 - .. function:: int json_array_remove(json_t *array, size_t index) Removes the element in *array* at position *index*, shifting the elements after *index* one position towards the start of the array. - Returns 0 on success and -1 on error. - - .. versionadded:: 1.1 + Returns 0 on success and -1 on error. The reference count of the + removed value is decremented. .. function:: int json_array_clear(json_t *array) Removes all elements from *array*. Returns 0 on sucess and -1 on - error. - - .. versionadded:: 1.1 + error. The reference count of all removed values are decremented. .. function:: int json_array_extend(json_t *array, json_t *other_array) Appends all elements in *other_array* to the end of *array*. Returns 0 on success and -1 on error. - .. versionadded:: 1.1 - Object ====== @@ -495,8 +513,6 @@ Unicode string and the value is any JSON value. Returns the number of elements in *object*, or 0 if *object* is not a JSON object. - .. versionadded:: 1.1 - .. function:: json_t *json_object_get(const json_t *object, const char *key) .. refcounting:: borrow @@ -518,16 +534,12 @@ Unicode string and the value is any JSON value. really is the case (e.g. you have already checked it by other means). - .. versionadded:: 1.2 - .. function:: int json_object_set_new(json_t *object, const char *key, json_t *value) Like :func:`json_object_set()` but steals the reference to *value*. This is useful when *value* is newly created and not used after the call. - .. versionadded:: 1.1 - .. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value) Like :func:`json_object_set_new`, but doesn't check that *key* is @@ -535,30 +547,73 @@ Unicode string and the value is any JSON value. really is the case (e.g. you have already checked it by other means). - .. versionadded:: 1.2 - .. function:: int json_object_del(json_t *object, const char *key) Delete *key* from *object* if it exists. Returns 0 on success, or - -1 if *key* was not found. - + -1 if *key* was not found. The reference count of the removed value + is decremented. .. function:: int json_object_clear(json_t *object) Remove all elements from *object*. Returns 0 on success and -1 if - *object* is not a JSON object. - - .. versionadded:: 1.1 + *object* is not a JSON object. The reference count of all removed + values are decremented. .. function:: int json_object_update(json_t *object, json_t *other) Update *object* with the key-value pairs from *other*, overwriting existing keys. Returns 0 on success or -1 on error. - .. versionadded:: 1.1 +.. function:: int json_object_update_existing(json_t *object, json_t *other) + + Like :func:`json_object_update()`, but only the values of existing + keys are updated. No new keys are created. Returns 0 on success or + -1 on error. + + .. versionadded:: 2.3 + +.. function:: int json_object_update_missing(json_t *object, json_t *other) + + Like :func:`json_object_update()`, but only new keys are created. + The value of any existing key is not changed. Returns 0 on success + or -1 on error. + + .. versionadded:: 2.3 +The following macro can be used to iterate through all key-value pairs +in an object. -The following functions implement an iteration protocol for objects: +.. function:: json_object_foreach(object, key, value) + + Iterate over every key-value pair of ``object``, running the block + of code that follows each time with the proper values set to + variables ``key`` and ``value``, of types :type:`const char *` and + :type:`json_t *` respectively. Example:: + + /* obj is a JSON object */ + const char *key; + json_t *value; + + json_object_foreach(obj, key, value) { + /* block of code that uses key and value */ + } + + The items are not returned in any particular order. + + This macro expands to an ordinary ``for`` statement upon + preprocessing, so its performance is equivalent to that of + hand-written iteration code using the object iteration protocol + (see below). The main advantage of this macro is that it abstracts + away the complexity behind iteration, and makes for shorter, more + concise code. + + .. versionadded:: 2.3 + + +The following functions implement an iteration protocol for objects, +allowing to iterate through all key-value pairs in an object. The +items are not returned in any particular order, as this would require +sorting due to the internal hashtable implementation. .. function:: void *json_object_iter(json_t *object) @@ -573,8 +628,6 @@ The following functions implement an iteration protocol for objects: *object* only yields all key-value pairs of the object if *key* happens to be the first key in the underlying hash table. - .. versionadded:: 1.3 - .. function:: void *json_object_iter_next(json_t *object, void *iter) Returns an iterator pointing to the next key-value pair in *object* @@ -596,21 +649,27 @@ The following functions implement an iteration protocol for objects: Set the value of the key-value pair in *object*, that is pointed to by *iter*, to *value*. - .. versionadded:: 1.3 - .. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value) Like :func:`json_object_iter_set()`, but steals the reference to *value*. This is useful when *value* is newly created and not used after the call. - .. versionadded:: 1.3 +.. function:: void *json_object_key_to_iter(const char *key) + + Like :func:`json_object_iter_at()`, but much faster. Only works for + values returned by :func:`json_object_iter_key()`. Using other keys + will lead to segfaults. This function is used internally to + implement :func:`json_object_foreach`. + + .. versionadded:: 2.3 The iteration protocol can be used for example as follows:: /* obj is a JSON object */ const char *key; json_t *value; + void *iter = json_object_iter(obj); while(iter) { @@ -621,12 +680,72 @@ The iteration protocol can be used for example as follows:: } +Error reporting +=============== + +Jansson uses a single struct type to pass error information to the +user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and +:ref:`apiref-unpack` for functions that pass error information using +this struct. + +.. type:: json_error_t + + .. member:: char text[] + + The error message (in UTF-8), or an empty string if a message is + not available. + + .. member:: char source[] + + Source of the error. This can be (a part of) the file name or a + special identifier in angle brackers (e.g. ````). + + .. member:: int line + + The line number on which the error occurred. + + .. member:: int column + + The column on which the error occurred. Note that this is the + *character column*, not the byte column, i.e. a multibyte UTF-8 + character counts as one column. + + .. member:: size_t position + + The position in bytes from the start of the input. This is + useful for debugging Unicode encoding problems. + +The normal use of :type:`json_error_t` is to allocate it on the stack, +and pass a pointer to a function. Example:: + + int main() { + json_t *json; + json_error_t error; + + json = json_load_file("/path/to/file.json", 0, &error); + if(!json) { + /* the error variable contains error information */ + } + ... + } + +Also note that if the call succeeded (``json != NULL`` in the above +example), the contents of ``error`` are generally left unspecified. +The decoding functions write to the ``position`` member also on +success. See :ref:`apiref-decoding` for more info. + +All functions also accept *NULL* as the :type:`json_error_t` pointer, +in which case no error information is returned to the caller. + + Encoding ======== This sections describes the functions that can be used to encode -values to JSON. Only objects and arrays can be encoded, since they are -the only valid "root" values of a JSON text. +values to JSON. By default, only objects and arrays can be encoded +directly, since they are the only valid *root* values of a JSON text. +To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see +below). By default, the output has no newlines, and spaces are used between array and object elements for a readable output. This behavior can be @@ -641,9 +760,9 @@ can be ORed together to obtain *flags*. ``JSON_INDENT(n)`` Pretty-print the result, using newlines between array and object items, and indenting with *n* spaces. The valid range for *n* is - between 0 and 32, other values result in an undefined output. If - ``JSON_INDENT`` is not used or *n* is 0, no newlines are inserted - between array and object items. + between 0 and 31 (inclusive), other values result in an undefined + output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are + inserted between array and object items. ``JSON_COMPACT`` This flag enables a compact representation, i.e. sets the separator @@ -651,29 +770,33 @@ can be ORed together to obtain *flags*. and values to ``":"``. Without this flag, the corresponding separators are ``", "`` and ``": "`` for more readable output. - .. versionadded:: 1.2 - ``JSON_ENSURE_ASCII`` If this flag is used, the output is guaranteed to consist only of ASCII characters. This is achived by escaping all Unicode characters outside the ASCII range. - .. versionadded:: 1.2 - ``JSON_SORT_KEYS`` If this flag is used, all the objects in output are sorted by key. This is useful e.g. if two JSON texts are diffed or visually compared. - .. versionadded:: 1.2 - ``JSON_PRESERVE_ORDER`` If this flag is used, object keys in the output are sorted into the same order in which they were first inserted to the object. For example, decoding a JSON text and then encoding with this flag preserves the order of object keys. - .. versionadded:: 1.3 +``JSON_ENCODE_ANY`` + Specifying this flag makes it possible to encode any JSON value on + its own. Without it, only objects and arrays can be passed as the + *root* value to the encoding functions. + + **Note:** Encoding any value may be useful in some scenarios, but + it's generally discouraged as it violates strict compatiblity with + :rfc:`4627`. If you use this flag, don't expect interoperatibility + with other JSON systems. + + .. versionadded:: 2.1 The following functions perform the actual JSON encoding. The result is in UTF-8. @@ -698,6 +821,32 @@ is in UTF-8. *path* already exists, it is overwritten. *flags* is described above. Returns 0 on success and -1 on error. +.. type:: json_dump_callback_t + + A typedef for a function that's called by + :func:`json_dump_callback()`:: + + typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data); + + *buffer* points to a buffer containing a chunk of output, *size* is + the length of the buffer, and *data* is the corresponding + :func:`json_dump_callback()` argument passed through. + + On error, the function should return -1 to stop the encoding + process. On success, it should return 0. + + .. versionadded:: 2.2 + +.. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags) + + Call *callback* repeatedly, passing a chunk of the JSON + representation of *root* each time. *flags* is described above. + Returns 0 on success and -1 on error. + + .. versionadded:: 2.2 + + +.. _apiref-decoding: Decoding ======== @@ -707,50 +856,66 @@ text to the Jansson representation of JSON data. The JSON specification requires that a JSON text is either a serialized array or object, and this requirement is also enforced with the following functions. In other words, the top level value in the JSON text being -decoded must be either array or object. +decoded must be either array or object. To decode any JSON value, use +the ``JSON_DECODE_ANY`` flag (see below). See :ref:`rfc-conformance` for a discussion on Jansson's conformance to the JSON specification. It explains many design decisions that affect especially the behavior of the decoder. -.. type:: json_error_t +Each function takes a *flags* parameter that can be used to control +the behavior of the decoder. Its default value is 0. The following +macros can be ORed together to obtain *flags*. - This data structure is used to return information on decoding - errors from the decoding functions. Its definition is repeated - here:: +``JSON_REJECT_DUPLICATES`` + Issue a decoding error if any JSON object in the input text + contains duplicate keys. Without this flag, the value of the last + occurence of each key ends up in the result. Key equivalence is + checked byte-by-byte, without special Unicode comparison + algorithms. - #define JSON_ERROR_TEXT_LENGTH 160 + .. versionadded:: 2.1 - typedef struct { - char text[JSON_ERROR_TEXT_LENGTH]; - int line; - } json_error_t; +``JSON_DECODE_ANY`` + By default, the decoder expects an array or object as the input. + With this flag enabled, the decoder accepts any valid JSON value. - *line* is the line number on which the error occurred, or -1 if - this information is not available. *text* contains the error - message (in UTF-8), or an empty string if a message is not - available. + **Note:** Decoding any value may be useful in some scenarios, but + it's generally discouraged as it violates strict compatiblity with + :rfc:`4627`. If you use this flag, don't expect interoperatibility + with other JSON systems. - The normal usef of :type:`json_error_t` is to allocate it normally - on the stack, and pass a pointer to a decoding function. Example:: + .. versionadded:: 2.3 - int main() { - json_t *json; - json_error_t error; +``JSON_DISABLE_EOF_CHECK`` + By default, the decoder expects that its whole input constitutes a + valid JSON text, and issues an error if there's extra data after + the otherwise valid JSON input. With this flag enabled, the decoder + stops after decoding a valid JSON array or object, and thus allows + extra data after the JSON text. - json = json_load_file("/path/to/file.json", 0, &error); - if(!json) { - /* the error variable contains error information */ - } - ... - } + Normally, reading will stop when the last ``]`` or ``}`` in the + JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and + ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra + UTF-8 code unit (up to 4 bytes of input). For example, decoding + ``4true`` correctly decodes the integer 4, but also reads the + ``t``. For this reason, if reading multiple consecutive values that + are not arrays or objects, they should be separated by at least one + whitespace character. - Also note that if the decoding succeeded (``json != NULL`` in the - above example), the contents of ``error`` are unspecified. + .. versionadded:: 2.1 - All decoding functions also accept *NULL* as the - :type:`json_error_t` pointer, in which case no error information - is returned to the caller. +Each function also takes an optional :type:`json_error_t` parameter +that is filled with error information if decoding fails. It's also +updated on success; the number of bytes of input read is written to +its ``position`` field. This is especially useful when using +``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts. + +.. versionadded:: 2.3 + Number of bytes of input read is written to the ``position`` field + of the :type:`json_error_t` structure. + +If no error or position information is needed, you can pass *NULL*. The following functions perform the actual JSON decoding. @@ -760,9 +925,19 @@ The following functions perform the actual JSON decoding. Decodes the JSON string *input* and returns the array or object it contains, or *NULL* on error, in which case *error* is filled with - information about the error. See above for discussion on the - *error* parameter. *flags* is currently unused, and should be set - to 0. + information about the error. *flags* is described above. + +.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error) + + .. refcounting:: new + + Decodes the JSON string *buffer*, whose length is *buflen*, and + returns the array or object it contains, or *NULL* on error, in + which case *error* is filled with information about the error. This + is similar to :func:`json_loads()` except that the string doesn't + need to be null-terminated. *flags* is described above. + + .. versionadded:: 2.1 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error) @@ -770,9 +945,18 @@ The following functions perform the actual JSON decoding. Decodes the JSON text in stream *input* and returns the array or object it contains, or *NULL* on error, in which case *error* is - filled with information about the error. See above for discussion - on the *error* parameter. *flags* is currently unused, and should - be set to 0. + filled with information about the error. *flags* is described + above. + + This function will start reading the input from whatever position + the input file was, without attempting to seek first. If an error + occurs, the file position will be left indeterminate. On success, + the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK`` + flag was used. In this case, the file position will be at the first + character after the last ``]`` or ``}`` in the JSON input. This + allows calling :func:`json_loadf()` on the same ``FILE`` object + multiple times, if the input consists of consecutive JSON texts, + possibly separated by whitespace. .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error) @@ -780,9 +964,263 @@ The following functions perform the actual JSON decoding. Decodes the JSON text in file *path* and returns the array or object it contains, or *NULL* on error, in which case *error* is - filled with information about the error. See above for discussion - on the *error* parameter. *flags* is currently unused, and should - be set to 0. + filled with information about the error. *flags* is described + above. + + +.. _apiref-pack: + +Building Values +=============== + +This section describes functions that help to create, or *pack*, +complex JSON values, especially nested objects and arrays. Value +building is based on a *format string* that is used to tell the +functions about the expected arguments. + +For example, the format string ``"i"`` specifies a single integer +value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s, +b]"`` specifies an array value with two strings and a boolean as its +items:: + + /* Create the JSON integer 42 */ + json_pack("i", 42); + + /* Create the JSON array ["foo", "bar", true] */ + json_pack("[ssb]", "foo", "bar", 1); + +Here's the full list of format characters. The type in parentheses +denotes the resulting JSON type, and the type in brackets (if any) +denotes the C type that is expected as the corresponding argument. + +``s`` (string) [const char \*] + Convert a NULL terminated UTF-8 string to a JSON string. + +``n`` (null) + Output a JSON null value. No argument is consumed. + +``b`` (boolean) [int] + Convert a C :type:`int` to JSON boolean value. Zero is converted + to ``false`` and non-zero to ``true``. + +``i`` (integer) [int] + Convert a C :type:`int` to JSON integer. + +``I`` (integer) [json_int_t] + Convert a C :type:`json_int_t` to JSON integer. + +``f`` (real) [double] + Convert a C :type:`double` to JSON real. + +``o`` (any value) [json_t \*] + Output any given JSON value as-is. If the value is added to an + array or object, the reference to the value passed to ``o`` is + stolen by the container. + +``O`` (any value) [json_t \*] + Like ``o``, but the argument's reference count is incremented. + This is useful if you pack into an array or object and want to + keep the reference for the JSON value consumed by ``O`` to + yourself. + +``[fmt]`` (array) + Build an array with contents from the inner format string. ``fmt`` + may contain objects and arrays, i.e. recursive value building is + supported. + +``{fmt}`` (object) + Build an object with contents from the inner format string + ``fmt``. The first, third, etc. format character represent a key, + and must be ``s`` (as object keys are always strings). The second, + fourth, etc. format character represent a value. Any value may be + an object or array, i.e. recursive value building is supported. + +The following functions compose the value building API: + +.. function:: json_t *json_pack(const char *fmt, ...) + + .. refcounting:: new + + Build a new JSON value according to the format string *fmt*. For + each format character (except for ``{}[]n``), one argument is + consumed and used to build the corresponding value. Returns *NULL* + on error. + +.. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...) + json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap) + + .. refcounting:: new + + Like :func:`json_pack()`, but an in the case of an error, an error + message is written to *error*, if it's not *NULL*. The *flags* + parameter is currently unused and should be set to 0. + + As only the errors in format string (and out-of-memory errors) can + be caught by the packer, these two functions are most likely only + useful for debugging format strings. + +More examples:: + + /* Build an empty JSON object */ + json_pack("{}"); + + /* Build the JSON object {"foo": 42, "bar": 7} */ + json_pack("{sisi}", "foo", 42, "bar", 7); + + /* Like above, ':', ',' and whitespace are ignored */ + json_pack("{s:i, s:i}", "foo", 42, "bar", 7); + + /* Build the JSON array [[1, 2], {"cool": true}] */ + json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1); + + +.. _apiref-unpack: + +Parsing and Validating Values +============================= + +This sectinon describes functions that help to validate complex values +and extract, or *unpack*, data from them. Like :ref:`building values +`, this is also based on format strings. + +While a JSON value is unpacked, the type specified in the format +string is checked to match that of the JSON value. This is the +validation part of the process. In addition to this, the unpacking +functions can also check that all items of arrays and objects are +unpacked. This check be enabled with the format character ``!`` or by +using the flag ``JSON_STRICT``. See below for details. + +Here's the full list of format characters. The type in parentheses +denotes the JSON type, and the type in brackets (if any) denotes the C +type whose address should be passed. + +``s`` (string) [const char \*] + Convert a JSON string to a pointer to a NULL terminated UTF-8 + string. The resulting string is extracted by using + :func:`json_string_value()` internally, so it exists as long as + there are still references to the corresponding JSON string. + +``n`` (null) + Expect a JSON null value. Nothing is extracted. + +``b`` (boolean) [int] + Convert a JSON boolean value to a C :type:`int`, so that ``true`` + is converted to 1 and ``false`` to 0. + +``i`` (integer) [int] + Convert a JSON integer to C :type:`int`. + +``I`` (integer) [json_int_t] + Convert a JSON integer to C :type:`json_int_t`. + +``f`` (real) [double] + Convert a JSON real to C :type:`double`. + +``F`` (integer or real) [double] + Convert a JSON number (integer or real) to C :type:`double`. + +``o`` (any value) [json_t \*] + Store a JSON value with no conversion to a :type:`json_t` pointer. + +``O`` (any value) [json_t \*] + Like ``O``, but the JSON value's reference count is incremented. + +``[fmt]`` (array) + Convert each item in the JSON array according to the inner format + string. ``fmt`` may contain objects and arrays, i.e. recursive + value extraction is supporetd. + +``{fmt}`` (object) + Convert each item in the JSON object according to the inner format + string ``fmt``. The first, third, etc. format character represent + a key, and must be ``s``. The corresponding argument to unpack + functions is read as the object key. The second fourth, etc. + format character represent a value and is written to the address + given as the corresponding argument. **Note** that every other + argument is read from and every other is written to. + + ``fmt`` may contain objects and arrays as values, i.e. recursive + value extraction is supporetd. + +``!`` + This special format character is used to enable the check that + all object and array items are accessed, on a per-value basis. It + must appear inside an array or object as the last format character + before the closing bracket or brace. To enable the check globally, + use the ``JSON_STRICT`` unpacking flag. + +``*`` + This special format character is the opposite of ``!``. If the + ``JSON_STRICT`` flag is used, ``*`` can be used to disable the + strict check on a per-value basis. It must appear inside an array + or object as the last format character before the closing bracket + or brace. + +The following functions compose the parsing and validation API: + +.. function:: int json_unpack(json_t *root, const char *fmt, ...) + + Validate and unpack the JSON value *root* according to the format + string *fmt*. Returns 0 on success and -1 on failure. + +.. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...) + int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap) + + Validate and unpack the JSON value *root* according to the format + string *fmt*. If an error occurs and *error* is not *NULL*, write + error information to *error*. *flags* can be used to control the + behaviour of the unpacker, see below for the flags. Returns 0 on + success and -1 on failure. + +.. note:: + + The first argument of all unpack functions is ``json_t *root`` + instead of ``const json_t *root``, because the use of ``O`` format + character causes the reference count of ``root``, or some value + reachable from ``root``, to be increased. Furthermore, the ``o`` + format character may be used to extract a value as-is, which allows + modifying the structure or contents of a value reachable from + ``root``. + + If the ``O`` and ``o`` format character are not used, it's + perfectly safe to cast a ``const json_t *`` variable to plain + ``json_t *`` when used with these functions. + +The following unpacking flags are available: + +``JSON_STRICT`` + Enable the extra validation step checking that all object and + array items are unpacked. This is equivalent to appending the + format character ``!`` to the end of every array and object in the + format string. + +``JSON_VALIDATE_ONLY`` + Don't extract any data, just validate the JSON value against the + given format string. Note that object keys must still be specified + after the format string. + +Examples:: + + /* root is the JSON integer 42 */ + int myint; + json_unpack(root, "i", &myint); + assert(myint == 42); + + /* root is the JSON object {"foo": "bar", "quux": true} */ + const char *str; + int boolean; + json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean); + assert(strcmp(str, "bar") == 0 && boolean == 1); + + /* root is the JSON array [[1, 2], {"baz": null} */ + json_error_t error; + json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz"); + /* returns 0 for validation success, nothing is extracted */ + + /* root is the JSON array [1, 2, 3, 4, 5] */ + int myint1, myint2; + json_unpack(root, "[ii!]", &myint1, &myint2); + /* returns -1 for failed validation */ Equality @@ -823,8 +1261,6 @@ equal. Returns 0 if they are inequal or one or both of the pointers are *NULL*. - .. versionadded:: 1.2 - Copying ======= @@ -847,12 +1283,82 @@ copied in a recursive fashion. Returns a shallow copy of *value*, or *NULL* on error. - .. versionadded:: 1.2 - .. function:: json_t *json_deep_copy(json_t *value) .. refcounting:: new Returns a deep copy of *value*, or *NULL* on error. - .. versionadded:: 1.2 + +.. _apiref-custom-memory-allocation: + +Custom Memory Allocation +======================== + +By default, Jansson uses :func:`malloc()` and :func:`free()` for +memory allocation. These functions can be overridden if custom +behavior is needed. + +.. type:: json_malloc_t + + A typedef for a function pointer with :func:`malloc()`'s + signature:: + + typedef void *(*json_malloc_t)(size_t); + +.. type:: json_free_t + + A typedef for a function pointer with :func:`free()`'s + signature:: + + typedef void (*json_free_t)(void *); + +.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn) + + Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead + of :func:`free()`. This function has to be called before any other + Jansson's API functions to ensure that all memory operations use + the same functions. + +Examples: + +Use the `Boehm's conservative garbage collector`_ for memory +operations:: + + json_set_alloc_funcs(GC_malloc, GC_free); + +.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/ + +Allow storing sensitive data (e.g. passwords or encryption keys) in +JSON structures by zeroing all memory when freed:: + + static void *secure_malloc(size_t size) + { + /* Store the memory area size in the beginning of the block */ + void *ptr = malloc(size + 8); + *((size_t *)ptr) = size; + return ptr + 8; + } + + static void secure_free(void *ptr) + { + size_t size; + + ptr -= 8; + size = *((size_t *)ptr); + + guaranteed_memset(ptr, 0, size); + free(ptr); + } + + int main() + { + json_set_alloc_funcs(secure_malloc, secure_free); + /* ... */ + } + +For more information about the issues of storing sensitive data in +memory, see +http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html. +The page also explains the :func:`guaranteed_memset()` function used +in the example and gives a sample implementation for it.