cjson学习篇四：cJSON API介绍

说明：

本文章旨在总结备份、方便以后查询，由于是个人总结，如有不对，欢迎指正；另外，内容大部分来自网络、书籍、和各类手册，如若侵权请告知，马上删帖致歉。

QQ 群号：513683159 【相互学习】

内容来源：

cjson库的使用以及源码阅读

函数介绍

基本功能函数

cJSON_Version()

函数原型：

CJSON_PUBLIC(const char*) cJSON_Version(void);

函数功能：以字符串的形式返回cJSON版本号。

参数介绍：无。

cJSON_InitHooks()

函数原型：

CJSON_PUBLIC(void) cJSON_InitHooks(cJSON_Hooks* hooks);

函数功能：为cJSON提供malloc, realloc和free函数

参数介绍：

cJSON_Hooks结构体中有两个函数指针。

cJSON_Delete()

函数原型：

CJSON_PUBLIC(void) cJSON_Delete(cJSON *item);

函数功能：删除一个cJSON实体和所有子实体

cJSON_HasObjectItem()

函数原型：

CJSON_PUBLIC(cJSON_bool) cJSON_HasObjectItem(const cJSON *object, const char *string);

函数功能：

creat 相关

原始json

CJSON_PUBLIC(cJSON *) cJSON_CreateRaw(const char *raw);
CJSON_PUBLIC(cJSON *) cJSON_CreateArray(void);			   //数组（等于创建了一个空的 [ ]）
CJSON_PUBLIC(cJSON *) cJSON_CreateObject(void);			   //对象（等于创建了一个空的 { }）

调用创建相应类型的cJSON项

CJSON_PUBLIC(cJSON *) cJSON_CreateNull(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateTrue(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateFalse(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateBool(cJSON_bool boolean);
CJSON_PUBLIC(cJSON *) cJSON_CreateNumber(double num);
CJSON_PUBLIC(cJSON *) cJSON_CreateString(const char *string);

创建计数项数组(Create XXX Array)

这些实用程序创建一个计数项数组。参数计数不能大于数字数组中的元素数，否则数组访问将超出边界。

CJSON_PUBLIC(cJSON *) cJSON_CreateIntArray(const int *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateFloatArray(const float *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateDoubleArray(const double *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateStringArray(const char *const *strings, int count);

Reference

创建一个valuestring引用字符串的字符串，这样它将不会被cJSON_Delete释放
CJSON_PUBLIC(cJSON *) cJSON_CreateStringReference(const char *string)
创建一个只引用它的元素的对象/数组，这样它们就不会被cJSON_Delete释放
CJSON_PUBLIC(cJSON *) cJSON_CreateObjectReference(const cJSON *child);
CJSON_PUBLIC(cJSON *) cJSON_CreateArrayReference(const cJSON *child);

add 相关

将item添加到指定的数组/对象(AddItemTo XXX)

CJSON_PUBLIC(cJSON_bool) cJSON_AddItemToArray(cJSON *array, cJSON *item);
CJSON_PUBLIC(cJSON_bool) cJSON_AddItemToObject(cJSON *object, const char *string, cJSON *item);

当string明确是const(即字面量，或其他类似的常量)，并且肯定会在cJSON对象中保存下来时使用这个。

WARNING:当使用此函数时，请确保在写入’ tem->string '之前始终检查(item->type & cJSON_StringIsConst)是否为零。

将对item的引用附加到指定的数组/对象。当您想要将现有的cJSON添加到新的cJSON中，但又不想破坏现有的cJSON时，请使用此方法。

CJSON_PUBLIC(cJSON_bool) cJSON_AddItemReferenceToArray(cJSON *array, cJSON *item);
CJSON_PUBLIC(cJSON_bool) cJSON_AddItemReferenceToObject(cJSON *object, const char *string, cJSON *item);

用于同时创建和添加项到对象的辅助函数。如果失败，则返回添加的项或NULL。

CJSON_PUBLIC(cJSON*) cJSON_AddNullToObject(cJSON * const object, const char * const name);
CJSON_PUBLIC(cJSON*) cJSON_AddTrueToObject(cJSON * const object, const char * const name);
CJSON_PUBLIC(cJSON*) cJSON_AddFalseToObject(cJSON * const object, const char * const name);
CJSON_PUBLIC(cJSON*) cJSON_AddBoolToObject(cJSON * const object, const char * const name, const cJSON_bool boolean);
CJSON_PUBLIC(cJSON*) cJSON_AddNumberToObject(cJSON * const object, const char * const name, const double number);
CJSON_PUBLIC(cJSON*) cJSON_AddStringToObject(cJSON * const object, const char * const name, const char * const string);
CJSON_PUBLIC(cJSON*) cJSON_AddRawToObject(cJSON * const object, const char * const name, const char * const raw);
CJSON_PUBLIC(cJSON*) cJSON_AddObjectToObject(cJSON * const object, const char * const name);
CJSON_PUBLIC(cJSON*) cJSON_AddArrayToObject(cJSON * const object, const char * const name);

Parse 相关

CJSON_PUBLIC(cJSON *) cJSON_Parse(const char *value);
CJSON_PUBLIC(cJSON *) cJSON_ParseWithLength(const char *value, size_t buffer_length);
CJSON_PUBLIC(cJSON *) cJSON_ParseWithOpts(const char *value, const char **return_parse_end, cJSON_bool require_null_terminated);
CJSON_PUBLIC(cJSON *) cJSON_ParseWithLengthOpts(const char *value, size_t buffer_length, const char **return_parse_end, cJSON_bool require_null_terminated);

cJSON_Parse()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_Parse(const char *value);

函数功能：内存管理:调用者总是负责释放cJSON_Parse(使用cJSON_Delete)和cJSON_Print(使用stdlib free、cJSON_Hooks.free_fn或cJSON_free)的所有变体的结果。异常是cJSON_PrintPreallocated，其中调用者对缓冲区负全部责任。

提供一个JSON块，这将返回一个可以查询的cJSON对象。

cJSON_ParseWithLength ()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_ParseWithLength(const char *value, size_t buffer_length);

函数功能：

cJSON_ParseWithOpts ()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_ParseWithOpts(const char *value, const char **return_parse_end, cJSON_bool require_null_terminated);

函数功能： ParseWithOpts允许您要求(和检查)JSON是空终止的，并检索到解析的最后一个字节的指针。

如果在return_parse_end中提供一个ptr，但解析失败，那么return_parse_end将包含一个指向错误的指针，因此将匹配cJSON_GetErrorPtr()。

cJSON_ParseWithLengthOpts ()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_ParseWithLengthOpts(const char *value, size_t buffer_length, const char **return_parse_end, cJSON_bool require_null_terminated);

函数功能：

print 相关

CJSON_PUBLIC(char *) cJSON_Print(const cJSON *item);
CJSON_PUBLIC(char *) cJSON_PrintUnformatted(const cJSON *item)
CJSON_PUBLIC(char *) cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt);
CJSON_PUBLIC(char *) cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt);

cJSON_Print ()

函数原型：

CJSON_PUBLIC(char *) cJSON_Print(const cJSON *item);

函数功能：将cJSON实体渲染为文本以进行传输/存储。

（将 cJSON数据解析成 JSON字符串，输出带有空白字符，呈现为标准的 JSON格式）

cJSON_PrintUnformatted ()

函数原型：

CJSON_PUBLIC(char *) cJSON_PrintUnformatted(const cJSON *item)

函数功能：将cJSON实体渲染为文本以进行传输/存储，而不需要任何格式化

（将 cJSON数据解析成 JSON字符串，输出没有带有空白字符的 JSON格式）

cJSON_PrintBuffered ()

函数原型：

CJSON_PUBLIC(char *) cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt);

函数功能：使用缓冲策略将cJSON实体渲染为文本。预缓冲是对最终大小的猜测。猜测正确可以减少重新分配。Fmt =0表示未格式化，=1表示格式化。

（prebuffer：指定输出 buffer的初始大小，fmt：是否使用空白字符进行格式化）

cJSON_PrintPreallocated()

函数原型：

CJSON_PUBLIC(char *) cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt);

函数功能：使用已经在内存中分配的具有给定长度的缓冲区将cJSON实体渲染为文本。成功返回1，失败返回0。

（输出 JSON到静态 buffer，从而避免动态分配内存，当buffer大小不够时，调用失败，返回 0，成功时返回 1）

注意： cJSON在估计它将使用多少内存时并不总是100%准确的，所以为了安全起见，比实际需要多分配5个字节

get 相关

CJSON_PUBLIC(int) cJSON_GetArraySize(const cJSON *array);
CJSON_PUBLIC(cJSON *) cJSON_GetArrayItem(const cJSON *array, int index);
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItem(const cJSON * const object, const char * const string);
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItemCaseSensitive(const cJSON * const object, const char * const string);
CJSON_PUBLIC(const char *) cJSON_GetErrorPtr(void);

cJSON_GetArraySize()

函数原型：

CJSON_PUBLIC(int) cJSON_GetArraySize(const cJSON *array);

函数功能：返回数组(或对象)中的项数。

cJSON_GetArrayItem()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_GetArrayItem(const cJSON *array, int index);

函数功能：从数组“array”中检索项目编号“index”。如果不成功则返回NULL。

cJSON_GetObjectItem()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_GetObjectItem(const cJSON * const object, const char * const string);

函数功能：从object中获取item “string”。不分大小写

cJSON_GetObjectItemCaseSensitive()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_GetObjectItemCaseSensitive(const cJSON * const object, const char * const string);

函数功能：

cJSON_GetErrorPtr()

函数原型：

CJSON_PUBLIC(const char *) cJSON_GetErrorPtr(void);

函数功能：用于分析失败的解析。这将返回一个指向解析错误的指针。您可能需要往回看一些字符来理解它。在cJSON_Parse()返回0时定义。cJSON_Parse()成功时，返回0。

检查项类型并返回其值

CJSON_PUBLIC(char *) cJSON_GetStringValue(const cJSON * const item);
CJSON_PUBLIC(double) cJSON_GetNumberValue(const cJSON * const item);
<font color="blue" size="6">**Is 相关**</font>
### 检查项目的类型
```c
CJSON_PUBLIC(cJSON_bool) cJSON_IsInvalid(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsFalse(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsTrue(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsBool(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsNull(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsNumber(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsString(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsArray(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsObject(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsRaw(const cJSON * const item);

Detach 相关

从数组/对象中移除/分离项

CJSON_PUBLIC(cJSON *) cJSON_DetachItemViaPointer(cJSON *parent, cJSON * const item);
CJSON_PUBLIC(cJSON *) cJSON_DetachItemFromArray(cJSON *array, int which);
CJSON_PUBLIC(void) cJSON_DeleteItemFromArray(cJSON *array, int which);
CJSON_PUBLIC(cJSON *) cJSON_DetachItemFromObject(cJSON *object, const char *string);
CJSON_PUBLIC(cJSON *) cJSON_DetachItemFromObjectCaseSensitive(cJSON *object, const char *string);
CJSON_PUBLIC(void) cJSON_DeleteItemFromObject(cJSON *object, const char *string);
CJSON_PUBLIC(void) cJSON_DeleteItemFromObjectCaseSensitive(cJSON *object, const char *string);

宏

当分配一个整数值时，它也需要传播给valuedouble。
#define cJSON_SetIntValue(object, number) ((object) ? (object)->valueint = (object)->valuedouble = (number) : (number))
宏cJSON_SetNumberValue的帮助器
CJSON_PUBLIC(double) cJSON_SetNumberHelper(cJSON *object, double number);
#define cJSON_SetNumberValue(object, number) ((object != NULL) ? cJSON_SetNumberHelper(object, (double)number) : (number))
修改cJSON_String对象的值字符串，仅当“对象类型”为cJSON_String时生效
CJSON_PUBLIC(char*) cJSON_SetValuestring(cJSON *object, const char *valuestring);
宏，用于在数组或对象上迭代
#define cJSON_ArrayForEach(element, array) for(element = (array != NULL) ? (array)->child : NULL; element != NULL; element = element->next)

更新数组项。

CJSON_PUBLIC(cJSON_bool) cJSON_InsertItemInArray(cJSON *array, int which, cJSON *newitem); /* Shifts pre-existing items to the right. */
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON * const item, cJSON * replacement);
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem);
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemInObject(cJSON *object,const char *string,cJSON *newitem);
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemInObjectCaseSensitive(cJSON *object,const char *string,cJSON *newitem);

使用使用cJSON_InitHooks设置的malloc/free函数的malloc/free对象

CJSON_PUBLIC(void *) cJSON_malloc(size_t size);
CJSON_PUBLIC(void) cJSON_free(void *object);

cJSON_Duplicate ()

函数原型：

CJSON_PUBLIC(cJSON *) cJSON_Duplicate(const cJSON *item, cJSON_bool recurse);

函数功能： Duplicate将在需要释放的新内存中创建一个新的、相同的cJSON项。递归!=0时，它将复制连接到该项的任何子项。item->next和>prev指针在从Duplicate返回时始终为零。

cJSON_Compare()

函数原型：

CJSON_PUBLIC(cJSON_bool) cJSON_Compare(const cJSON * const a, const cJSON * const b, const cJSON_bool case_sensitive);

函数功能：递归地比较两个cJSON项是否相等。如果a或b是NULL或无效，它们将被认为是不相等的。Case_sensitive确定对象键是区分大小写(1)还是不区分大小写(0)

cJSON_Minify ()

函数原型：

CJSON_PUBLIC(void) cJSON_Minify(char *json);

函数功能：最小化字符串，从字符串中删除空白字符(如’ ‘，’\t’， ‘\r’， ‘\n’)。输入指针json不能指向只读的地址区域，比如字符串常量，但应该指向可读和可写的地址区域。

cjson学习篇四：cJSON API介绍

函数介绍

基本功能函数

cJSON_Version()

cJSON_InitHooks()

cJSON_Delete()

cJSON_HasObjectItem()

原始json

调用创建相应类型的cJSON项

创建计数项数组(Create XXX Array)

Reference

将item添加到指定的数组/对象(AddItemTo XXX)

用于同时创建和添加项到对象的辅助函数。如果失败，则返回添加的项或NULL。

cJSON_Parse()

cJSON_ParseWithLength ()

cJSON_ParseWithOpts ()

cJSON_ParseWithLengthOpts ()

cJSON_Print ()

cJSON_PrintUnformatted ()

cJSON_PrintBuffered ()

cJSON_PrintPreallocated()

cJSON_GetArraySize()

cJSON_GetArrayItem()

cJSON_GetObjectItem()

cJSON_GetObjectItemCaseSensitive()

cJSON_GetErrorPtr()

检查项类型并返回其值

从数组/对象中移除/分离项

宏

更新数组项。

使用使用cJSON_InitHooks设置的malloc/free函数的malloc/free对象

cJSON_Duplicate ()

cJSON_Compare()

cJSON_Minify ()

继续阅读