json使用

 

#include <jansson.h>

in each source file.

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

The JSON specification (RFC 4627) defines the following data types: object, array, string, number, boolean, and null. JSON types are used dynamically; arrays and objects can hold any other data type, including themselves. For this reason, Jansson’s type system is also dynamic in nature. There’s one C type to represent all JSON values, and this structure knows the type of the JSON value it holds.

json_t

This data structure is used throughout the library to represent all JSON values. It always contains the type of the JSON value it holds and the value’s reference count. The rest depends on the type of the value.

Objects of json_t are always used through a pointer. There are APIs for querying the type, manipulating the reference count, and for constructing and manipulating values of different types.

Unless noted otherwise, all API functions return an error value if an error occurs. Depending on the function’s signature, the error value is either NULL or -1. Invalid arguments or invalid input are apparent sources for errors. Memory allocation and I/O operations may also cause errors.

Type

The type of a JSON value is queried and tested using the following functions:

enum json_type

The type of a JSON value. The following members are defined:

JSON_OBJECT

JSON_ARRAY

JSON_STRING

JSON_INTEGER

JSON_REAL

JSON_TRUE

JSON_FALSE

JSON_NULL

These correspond to JSON object, array, string, number, boolean and null. A number is represented by either a value of the type JSON_INTEGER or of the type JSON_REAL. A true boolean value is represented by a value of the type JSON_TRUE and false by a value of the type JSON_FALSE.

int json_typeof (const json_t  *json )

Return the type of the JSON value a json_type cast to int). json MUST NOT be NULL. This function is actually implemented as a macro for speed.

json_is_object (const json_t  *json ) json_is_array (const json_t  *json ) json_is_string (const json_t  *json ) json_is_integer (const json_t  *json ) json_is_real (const json_t  *json ) json_is_true (const json_t  *json ) json_is_false (const json_t  *json ) json_is_null (const json_t  *json )

These functions (actually macros) return true (non-zero) for values of the given type, and false (zero) for values of other types and for NULL.

json_is_number (const json_t  *json )

Returns true for values of types JSON_INTEGER and JSON_REAL, and false for other types and for NULL.

json_is_boolean (const json_t  *json )

Returns true for types JSON_TRUE and JSON_FALSE, and false for values of other types and for NULL.

Reference Count

The reference count is used to track whether a value is still in use or not. When a value is created, it’s reference count is set to 1. If a reference to a value is kept (e.g. a value is stored somewhere for later use), its reference count is incremented, and when the value is no longer needed, the reference count is decremented. When the reference count drops to zero, there are no references left, and the value can be destroyed.

The following functions are used to manipulate the reference count.

json_t * json_incref ( json_t  *json )

Increment the reference count of json if it’s not non-NULL. Returns json.

void json_decref ( json_t  *json )

Decrement the reference count of json. As soon as a call to json_decref() drops the reference count to zero, the value is destroyed and it can no longer be used.

Functions creating new JSON values set the reference count to 1. These functions are said to return a new reference. Other functions returning (existing) JSON values do not normally increase the reference count. These functions are said to return a borrowed reference. So, if the user will hold a reference to a value returned as a borrowed reference, he must call json_incref(). As soon as the value is no longer needed, json_decref() should be called to release the reference.

Normally, all functions accepting a JSON value as an argument will manage the reference, i.e. increase and decrease the reference count as needed. However, some functions steal the reference, i.e. they have the same result as if the user called json_decref() on the argument right after calling the function. These functions are suffixed with _new or have _new_ somewhere in their name.

For example, the following code creates a new JSON array and appends an integer to it:

json_t *array, *integer;

array = json_array();
integer = json_integer(42);

json_array_append(array, integer);
json_decref(integer);

Note how the caller has to release the reference to the integer value by calling json_decref(). By using a reference stealing function json_array_append_new() instead of json_array_append(), the code becomes much simpler:

json_t *array = json_array();
json_array_append_new(array, json_integer(42));

In this case, the user doesn’t have to explicitly release the reference to the integer value, as json_array_append_new() steals the reference when appending the value to the array.

In the following sections it is clearly documented whether a function will return a new or borrowed reference or steal a reference to its argument.

Circular References

A circular reference is created when an object or an array is, directly or indirectly, inserted inside itself. The direct case is simple:

json_t *obj = json_object();
json_object_set(obj, "foo", obj);

Jansson will refuse to do this, and json_object_set() (and all the other such functions for objects and arrays) will return with an error status. The indirect case is the dangerous one:

json_t *arr1 = json_array(), *arr2 = json_array();
json_array_append(arr1, arr2);
json_array_append(arr2, arr1);

In this example, the array arr2 is contained in the array arr1, and vice versa. Jansson cannot check for this kind of indirect circular references without a performance hit, so it’s up to the user to avoid them.

If a circular reference is created, the memory consumed by the values cannot be freed by json_decref(). The reference counts never drops to zero because the values are keeping the references to each other. Moreover, trying to encode the values with any of the encoding functions will fail. The encoder detects circular references and returns an error status.

True, False and Null

These values are implemented as singletons, so each of these functions returns the same value each time.

json_t * json_true (void )

Return value: New reference.

Returns the JSON true value.

json_t * json_false (void )

Return value: New reference.

Returns the JSON false value.

json_t * json_null (void )

Return value: New reference.