没有合适的资源?快使用搜索试试~ 我知道了~
Keil提供的JSON库的使用参数说明--API Reference — Jansson 2
4星 · 超过85%的资源 需积分: 49 57 下载量 70 浏览量
2017-12-15
12:43:47
上传
评论
收藏 794KB PDF 举报
温馨提示
keil提供的JSON库——Jansson API Reference Preliminaries All declara ons are in jansson.h , so it’s enough to #include <jansson.h> in each source file. All constants are prefixed with JSON_ (except for those describing the library version, prefixed with JANSSON_ ). Other iden fiers are prefixed with json_ . Type names are suffixed with _t and typedef ‘d so that the struct keyword need not be used.
资源推荐
资源详情
资源评论
Docs » API Reference
API Reference
Preliminaries
All declara ons are in
jansson.h
, so it’s enough to
#include <jansson.h>
in each source file.
All constants are prefixed with
JSON_
(except for those describing the library version, prefixed with
JANSSON_
). Other iden fiers 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 omi ed 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 func onality, the micro version
is incremented. When new features are added in a backwards compa ble way, the minor version is
incremented and the micro version is set to zero. When there are backwards incompa ble changes,
the major version is incremented and others are set to zero.
The following preprocessor constants specify the current version of the library:
JANSSON_MAJOR_VERSION , JANSSON_MINOR_VERSION , JANSSON_MICRO_VERSION
Integers specifying the major, minor and micro versions, respec vely.
JANSSON_VERSION
A string representa on of the current version, e.g.
"1.2.1"
or
"1.3"
.
JANSSON_VERSION_HEX
A 3-byte hexadecimal representa on of the version, e.g.
0x010201
for version 1.2.1 and 0x010300
for version 1.3. This is useful in numeric comparisons, e.g.:
#if JANSSON_VERSION_HEX >= 0x010300
/* Code specific to version 1.3 and above */ #endif
Value Representation
The JSON specifica on (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, manipula
ng the reference count, and for construc ng and manipula ng values of different types.
Unless noted otherwise, all API func ons return an error value if an error occurs. Depending on the
func on’s signature, the error value is either NULL or -1. Invalid arguments or invalid input are
apparent sources for errors. Memory alloca on and I/O opera ons may also cause errors.
Type
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 func
on 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 func ons (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.
json_boolean_value(const json_t *json)
Alias of
json_is_true()
, i.e. returns 1 for
JSON_TRUE
and 0 otherwise.
New in version 2.7.
Reference Count
The reference count is used to track whether a value is s ll 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
le , and the value can be destroyed.
json_t *json_incref(json_t *json)
Increment the reference count of json if it’s not 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.
Func ons crea ng new JSON values set the reference count to 1. These func ons are said to return a
new reference. Other func ons returning (exis ng) JSON values do not normally increase the
reference count. These func ons 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 func ons accep ng a JSON value as an argument will manage the reference, i.e. increase
and decrease the reference count as needed. However, some func ons steal the reference, i.e. they
have the same result as if the user called
json_decref()
on the argument right a er calling the func on.
These func ons 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 func on 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 sec ons it is clearly documented whether a func on 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 func ons 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 func ons
will fail. The encoder detects circular references and returns an error status.
Scope Dereferencing
New in version 2.9.
It is possible to use the
json_auto_t
type to automa cally dereference a value at the end of a scope.
For example:
void function(void)
{ json_auto_t *value = NULL;
value = json_string("foo");
/* json_decref(value) is automatically called. */ }
This feature is only available on GCC and Clang. So if your project has a portability requirement for
other compilers, you should avoid this feature.
Addi onally, as always, care should be taken when passing values to func ons that steal references.
True, False and Null
These three values are implemented as singletons, so the returned pointers won’t change between
invoca ons of these func ons.
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_boolean(val)
Return value: New reference.
剩余28页未读,继续阅读
资源评论
- 张子楠Aaron2018-06-29和官方的一样....有些浪费了
HnaLin
- 粉丝: 2
- 资源: 4
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
最新资源
资源上传下载、课程学习等过程中有任何疑问或建议,欢迎提出宝贵意见哦~我们会及时处理!
点击此处反馈
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功