WS53指导资料

- hardware
  - SoC Wi-Fi、BLE和SLE Combo芯片 硬件用户指南
    - 前言
    - 封装与管脚
    - 电性能参数
    - 原理图设计建议
    - PCB设计建议
    - 热设计建议
    - 焊接工艺
    - 潮敏参数
    - 接口时序
    - 注意事项
    - 缩略语
  - 单板硬件关键器件选型指导
    - 前言
    - 关键器件选型约束
  - 射频测试 用户指南
    - 前言
    - 测试指令
    - 注意事项
- 软件资料
  - AT命令 使用指南
    - 前言
    - 指令说明
    - Wi-Fi模块AT指令
    - BLE&SLE模块AT指令
    - PLAT模块AT指令
  - BLE BQB认证测试 指导书
    - 前言
    - 蓝牙BQB认证简介
    - BQB协议认证
    - BQB 射频认证
    - WS53特性支持情况
    - 常见问题&测试命令汇总(FAQ)
  - BOOT API开发参考
    - 前言
    - 接口介绍
  - Boot移植应用 开发指南
    - 前言
    - Boot简介
    - RomBoot功能说明
    - LoaderBoot功能说明
    - FlashBoot说明
  - CJSON 开发指南
    - 前言
    - API接口说明
    - 开发指南
  - CoAP 开发指南
    - 前言
    - API接口说明
    - 开发指南
  - EFUSE 使用指南
    - 前言
    - 概述
    - 软件编程接口使用指导
    - Burntool烧写efuse_cfg.bin说明
  - FOTA 开发指南
    - 前言
    - 概述
    - 升级包制作
    - 升级包传输
    - 升级包保存
    - 升级包本地升级
    - AB面升级
    - FAQ
  - HTTP 开发指南
    - 前言
    - 开发指南
  - MQTT 开发指南
    - 前言
    - API接口描述
    - 开发指南
    - 注意事项
  - NV存储 用户指南
    - 前言
    - NV简介
    - NV编译预置
    - NV API指南
    - NV项汇总
  - SAMPLE用例 用户指南
    - 前言
    - SAMPLE简介
    - 外设SAMPLE用例
  - SDK 开发指南
    - 前言
    - 概述
    - 系统接口
  - SDK开发环境搭建 用户指南
    - 前言
    - 开发环境搭建
    - 编译
    - 新建APP
  - Syschannel 使用指南
    - 前言
    - Syschannel 简介
    - Syschannel 使用指南
    - Syschannel 编译指导
    - Syschannel 适配常见问题
  - TLS&DTLS 开发指南
    - 前言
    - API接口说明
    - 开发指南
    - 硬件适配
    - 注意事项
  - WFA认证测试指导书
    - 前言
    - WLAN WFA协议认证介绍
    - WS53 WFA认证
    - 缩略语
  - lwIP 开发指南
    - 前言
    - 概述
    - 功能特性
    - 开发指引
    - 网络安全
    - 常见问题
    - 术语
  - 产测FAQ
    - 前言
    - FAQ
    - 注意事项
    - 版本问题记录
  - 产线工装 用户指南
    - 前言
    - 测试软件准备
    - 单板测试方案
    - TX/RX测试参考
    - WLAN Facility与固件版本
    - 产线生产ESD防护要求
  - 低功耗 开发指南
    - 前言
    - 概述
    - 超深睡模式
    - 深睡模式
    - 浅睡模式
    - 常见问题
  - 单板冒烟 测试指南
    - 前言
    - 概述
    - 单板冒烟测试
  - 安全模块 使用指南
    - 前言
    - 概述
    - 错误码
    - 网络安全注意事项
  - 文件系统 使用指南
    - 前言
    - LFS简介
    - LFS编译预置
    - LFS接口API
  - 星闪认证测试 指导书
    - 前言
    - 星闪认证简介
    - 星闪协议认证
    - 星闪射频认证
    - 星闪特性支持
    - 常见问题&测试命令汇总（FAQ）
  - 特性开发说明书
    - 前言
    - 混杂模式特性说明
    - 动态国家码特性说明
    - BLE配网特性说明
    - 安全启动特性说明
    - FLASH在线解密特性说明
  - 第三方软件 移植指南
    - 前言
    - 移植指引
    - 常见问题
  - 设备驱动 开发指南
    - 前言
    - Pinctrl
    - GPIO
    - UART
    - SPI
    - QSPI
    - I2C
    - ADC
    - DMA
    - PWM
    - WDT
    - Timer
    - Systick
    - TCXO
    - SFC
    - eFuse
    - REBOOT
    - I2S
  - 软件 开发指南
    - 前言
    - 概述
    - Wi-Fi 软件开发指南
    - BLE&SLE 软件开发指南
    - 注意事项
  - 运维手册
    - 前言
    - 系统/平台模块
    - Wi-Fi模块
  - 鸿蒙XTS认证 指导书
    - 前言
    - 概述
    - 准备工作
    - 编译openharmony静态库
    - XTS版本编译和执行

### 该页内容

- 前言
- API接口说明
  - 结构体说明
    - struct cJSON
    - struct cJSON_Hooks
  - API列表
- 开发指南
  - 创建Json字符串示例
  - 解析Json字符串示例

# 前言

概述

CJSON是一个轻量级、‌易于使用的C语言库，‌用于处理JSON数据。‌使用CcJSON，‌开发者可以轻松地创建JSON对象、‌添加数据、‌解析JSON字符串，‌以及遍历和处理JSON数据。‌

本文档主要介绍基于CJSON 1.7.15的JSON报文解析功能开发实现示例，以及接口说明。

CJSON 1.7.15的详细说明请参见官方说明文档：#README

产品版本

与本文档相对应的产品版本如下。

产品名称 | 产品版本
--- | ---
WS53 | V100

读者对象

本文档主要适用于以下工程师：

- 技术支持工程师

- 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号 | 说明
--- | ---
| 表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
| 表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
| 表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
| 用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
| 对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
01 | 2024-07-23 | 第一次正式版本发布。

# API接口说明

> 说明： cJson 1.7.15为开源软件，以下为部分结构体和API描述，其余部分请参考官方说明。

- 结构体说明

- API列表

## 结构体说明

- struct cJSON

- struct cJSON_Hooks

### struct cJSON

    /* The cJSON structure: */
    typedef struct cJSON
    {
    struct cJSON *next;
    struct cJSON *prev;
    struct cJSON *child;
    int type;
    char *valuestring;
    /* writing to valueint is DEPRECATED, use cJSON_SetNumberValue instead */
    int valueint;
    double valuedouble;
    char *string;
    } cJSON;

### struct cJSON_Hooks

    typedef struct cJSON_Hooks
    {
    /* malloc/free are CDECL on Windows regardless of the default calling convention of the compiler, so ensure the hooks allow passing those functions directly. */
    void *(CJSON_CDECL *malloc_fn)(size_t sz);
    void (CJSON_CDECL *free_fn)(void *ptr);
    } cJSON_Hooks;

## API列表

cJSON API | 说明
--- | ---
CJSON_PUBLIC(const char*) cJSON_Version(void); | 获得cJSON的版本。
CJSON_PUBLIC(void) cJSON_InitHooks(cJSON_Hooks* hooks); | 初始化cJSON_Hooks。
CJSON_PUBLIC(cJSON *) cJSON_Parse(const char *value); | 将字符串解析成cJSON结构体。
CJSON_PUBLIC(cJSON *) cJSON_ParseWithOpts(const char *value, const char **return_parse_end, cJSON_bool require_null_terminated);
CJSON_PUBLIC(char *) cJSON_Print(const cJSON *item); | 将cJSON结构体转换成格式化的字符串。
CJSON_PUBLIC(char *) cJSON_PrintUnformatted(const cJSON *item); | 将cJSON结构体转换成未格式化的字符串。
CJSON_PUBLIC(char *) cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt); | 将cJSON结构体转换为字符串，通过入参传入预估结果尺寸和是否格式化。
CJSON_PUBLIC(cJSON_bool) cJSON_PrintPreallocated(cJSON *item, char *buffer, const int length, const cJSON_bool format); | 将cJSON结构体转换为字符串，并存入预先申请的长度确定的缓冲空间，通过传入参数决定是否格式化。
CJSON_PUBLIC(void) cJSON_Delete(cJSON *c); | 删除cJSON结构体。
CJSON_PUBLIC(int) cJSON_GetArraySize(const cJSON *array); | 返回Array类型的大小，对Object类型也有效。
CJSON_PUBLIC(cJSON *) cJSON_GetArrayItem(const cJSON *array, int index); | 返回Array类型的index的值，对Object类型也有效。
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItem(const cJSON * const object, const char * const string); | 使用string获得对应的value。
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItemCaseSensitive(const cJSON * const object, const char * const string);
CJSON_PUBLIC(cJSON_bool) cJSON_HasObjectItem(const cJSON *object, const char *string); | 判断string在Object中是否存在。
CJSON_PUBLIC(const char *) cJSON_GetErrorPtr(void); | 获得错误信息。
CJSON_PUBLIC(char *) cJSON_GetStringValue(cJSON *item); | 判断Item是否为字符串，返回键值字符串或NULL。
CJSON_PUBLIC(cJSON_bool) cJSON_IsInvalid(const cJSON * const item); | 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);
CJSON_PUBLIC(cJSON *) cJSON_CreateNull(void); | 创造对应类型的Item。
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);
CJSON_PUBLIC(cJSON *) cJSON_CreateRaw(const char *raw);
CJSON_PUBLIC(cJSON *) cJSON_CreateArray(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateObject(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateIntArray(const int *numbers, int count); | 批量创造包含对应类型和数量Items的Array。
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 **strings, int count);
CJSON_PUBLIC(void) cJSON_AddItemToArray(cJSON *array, cJSON *item); | 向Array或Object增加Item。
CJSON_PUBLIC(void) cJSON_AddItemToObject(cJSON *object, const char *string, cJSON *item);
CJSON_PUBLIC(void) cJSON_AddItemToObjectCS(cJSON *object, const char *string, cJSON *item);
CJSON_PUBLIC(void) cJSON_AddItemReferenceToArray(cJSON *array, cJSON *item);
CJSON_PUBLIC(void) cJSON_AddItemReferenceToObject(cJSON *object, const char *string, cJSON *item);
CJSON_PUBLIC(cJSON *) cJSON_DetachItemViaPointer(cJSON *parent, cJSON * const item); | 从Arrays或Objects中删除Items。
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);
CJSON_PUBLIC(void) cJSON_InsertItemInArray(cJSON *array, int which, cJSON *newitem); | 更新Items。
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON * const item, cJSON * replacement);
CJSON_PUBLIC(void) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem);
CJSON_PUBLIC(void) cJSON_ReplaceItemInObject(cJSON *object,const char *string,cJSON *newitem);
CJSON_PUBLIC(void) cJSON_ReplaceItemInObjectCaseSensitive(cJSON *object,const char *string,cJSON *newitem);
CJSON_PUBLIC(cJSON *) cJSON_Duplicate(const cJSON *item, cJSON_bool recurse); | 复制cJSON结构体。
CJSON_PUBLIC(cJSON_bool) cJSON_Compare(const cJSON * const a, const cJSON * const b, const cJSON_bool case_sensitive); | 比较两个cJSON结构体。
CJSON_PUBLIC(void) cJSON_Minify(char *json); | 将格式化的字符串压缩。
CJSON_PUBLIC(cJSON*) cJSON_AddNullToObject(cJSON * const object, const char * const name); | 用于同时创建对象和将Items添加到Object。返回添加的Items或返回NULL表示失败。
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);
cJSON_SetIntValue(object, number) | 设置整形键值，同时设置双精度浮点型键值。
cJSON_SetNumberValue(object, number) | 设置双精度浮点型键值，同时设置整形键值。
cJSON_ArrayForEach(element, array) | 遍历数组。
CJSON_PUBLIC(double) cJSON_SetNumberHelper(cJSON *object, double number); | 设置整形和双精度浮点型键值，超过极限值的输入将按照极限值设置。
CJSON_PUBLIC(void *) cJSON_malloc(size_t size); | 使用cJSON_InitHooks中注册的函数实现malloc/free操作。
CJSON_PUBLIC(void) cJSON_free(void *object);

# 开发指南

以下为组织Json字符串和解析Json字符串的官方代码样例。

- 创建Json字符串示例

- 解析Json字符串示例

## 创建Json字符串示例

    //NOTE: Returns a heap allocated string, you are required to free it after use.
    char *create_monitor_with_helpers(void)
    {
        const unsigned int resolution_numbers[3][2] = {
            {1280, 720},
            {1920, 1080},
            {3840, 2160}
        };
        char *string = NULL;
        cJSON *resolutions = NULL;
        size_t index = 0;

        cJSON *monitor = cJSON_CreateObject();

        if (cJSON_AddStringToObject(monitor, "name", "Awesome 4K") == NULL)
        {
            goto end;
        }

        resolutions = cJSON_AddArrayToObject(monitor, "resolutions");
        if (resolutions == NULL)
        {
            goto end;
        }

        for (index = 0; index < (sizeof(resolution_numbers) / (2 * sizeof(int))); ++index)
        {
            cJSON *resolution = cJSON_CreateObject();

            if (cJSON_AddNumberToObject(resolution, "width", resolution_numbers[index][0]) == NULL)
            {
                goto end;
            }

            if(cJSON_AddNumberToObject(resolution, "height", resolution_numbers[index][1]) == NULL)
            {
                goto end;
            }

            cJSON_AddItemToArray(resolutions, resolution);
        }

        string = cJSON_Print(monitor);
        if (string == NULL) {
            fprintf(stderr, "Failed to print monitor.\n");
        }

    end:
        cJSON_Delete(monitor);
        return string;
    }

## 解析Json字符串示例

    /* return 1 if the monitor supports full hd, 0 otherwise */
    int supports_full_hd(const char * const monitor)
    {
        const cJSON *resolution = NULL;
        const cJSON *resolutions = NULL;
        const cJSON *name = NULL;
        int status = 0;
        cJSON *monitor_json = cJSON_Parse(monitor);
        if (monitor_json == NULL)
        {
            const char *error_ptr = cJSON_GetErrorPtr();
            if (error_ptr != NULL)
            {
                fprintf(stderr, "Error before: %s\n", error_ptr);
            }
            status = 0;
            goto end;
        }

        name = cJSON_GetObjectItemCaseSensitive(monitor_json, "name");
        if (cJSON_IsString(name) && (name->valuestring != NULL))
        {
            printf("Checking monitor \"%s\"\n", name->valuestring);
        }

        resolutions = cJSON_GetObjectItemCaseSensitive(monitor_json, "resolutions");
        cJSON_ArrayForEach(resolution, resolutions)
        {
            cJSON *width = cJSON_GetObjectItemCaseSensitive(resolution, "width");
            cJSON *height = cJSON_GetObjectItemCaseSensitive(resolution, "height");

            if (!cJSON_IsNumber(width) || !cJSON_IsNumber(height))
            {
                status = 0;
                goto end;
            }

            if ((width->valuedouble == 1920) && (height->valuedouble == 1080))
            {
                status = 1;
                goto end;
            }
        }

    end:
        cJSON_Delete(monitor_json);
        return status;
    }