X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=doc%2Fapiref.rst;h=79693fbe2b7733e317de672e584bfef95aeef355;hb=a33c3628da8434d91609574f7d07f3c90bb8fe00;hp=397f4187142cfe71015075ed1fd279bd3cbb701a;hpb=781bda140418821ad79ef513b0fd8cfbc0ce552e;p=jansson.git diff --git a/doc/apiref.rst b/doc/apiref.rst index 397f418..79693fb 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,34 @@ 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 - .. function:: int json_array_clear(json_t *array) Removes all elements from *array*. Returns 0 on sucess and -1 on error. - .. versionadded:: 1.1 - .. 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 +512,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 +533,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,8 +546,6 @@ 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 @@ -548,15 +557,11 @@ Unicode string and the value is any JSON value. Remove all elements from *object*. Returns 0 on success and -1 if *object* is not a JSON object. - .. versionadded:: 1.1 - .. 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 - The following functions implement an iteration protocol for objects: @@ -573,8 +578,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,16 +599,12 @@ 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 - The iteration protocol can be used for example as follows:: /* obj is a JSON object */ @@ -621,6 +620,62 @@ 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 unspecified. + +All functions also accept *NULL* as the :type:`json_error_t` pointer, +in which case no error information is returned to the caller. + + Encoding ======== @@ -651,30 +706,22 @@ 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 - The following functions perform the actual JSON encoding. The result is in UTF-8. @@ -699,6 +746,8 @@ is in UTF-8. above. Returns 0 on success and -1 on error. +.. _apiref-decoding: + Decoding ======== @@ -713,76 +762,271 @@ 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 +.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error) - This data structure is used to return information on decoding - errors from the decoding functions. Its definition is repeated - here:: + .. refcounting:: new - #define JSON_ERROR_TEXT_LENGTH 160 + 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. *flags* is currently unused, and + should be set to 0. - typedef struct { - char text[JSON_ERROR_TEXT_LENGTH]; - int line; - } json_error_t; +.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error) - *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. + .. refcounting:: new - 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:: + 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. *flags* is currently + unused, and should be set to 0. - int main() { - json_t *json; - json_error_t error; +.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error) - json = json_load_file("/path/to/file.json", 0, &error); - if(!json) { - /* the error variable contains error information */ - } - ... - } + .. refcounting:: new - Also note that if the decoding succeeded (``json != NULL`` in the - above example), the contents of ``error`` are unspecified. + 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. *flags* is currently + unused, and should be set to 0. - All decoding functions also accept *NULL* as the - :type:`json_error_t` pointer, in which case no error information - is returned to the caller. -The following functions perform the actual JSON decoding. +.. _apiref-pack: -.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error) +Building values +=============== - .. refcounting:: new +This sectinon 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. - 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. +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 integers and a boolean as its +items:: -.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error) + /* 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 + stealed by the container. + +``O`` (any value) [json_t \*] + Like ``o``, but the argument's reference count is incremented. + This is useful if you pack and array 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 - 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. + 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_load_file(const char *path, size_t flags, json_error_t *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 - 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. + 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("{sisb}", "foo", 42, "bar", 7); + + /* Like above, ':', ',' and whitespace are ignored */ + json_pack("{s:i, s:b}", "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. + +``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. + +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 +1067,6 @@ equal. Returns 0 if they are inequal or one or both of the pointers are *NULL*. - .. versionadded:: 1.2 - Copying ======= @@ -847,12 +1089,80 @@ 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 + +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 examplains the :func:`guaranteed_memset()` function used +in the example and gives a sample implementation for it.