RTU_ALL_AI/docs/public/libcJSON/API-libcJSON.md

libcJSON — JSON 解析/生成库 API 参考

模块概述

libcJSON 是开源的轻量级 JSON 解析/生成库（MIT 许可证），直接使用原工程版本。 基于递归下降解析器 + 树状内存模型。支持 object/array/string/number/boolean/null。

数据结构

typedef enum
{   CJSON_NULL = 0, CJSON_FALSE, CJSON_TRUE,
    CJSON_NUMBER, CJSON_STRING, CJSON_ARRAY, CJSON_OBJECT
} enum_cjson_type;

typedef struct cjson
{
    struct cjson   *next, *prev;  // 兄弟节点链表
    struct cjson   *child;        // 子节点（对象/数组的第一个子元素）
    enum_cjson_type type;
    char            *key;         // 对象键名
    char            *val_str;     // 字符串值
    double           val_num;     // 数值
} stru_cjson;

接口函数

解析与释放

函数	说明
cJSON_Parse(json)	解析 JSON 字符串，返回根节点
cJSON_Delete(node)	递归释放整棵树

查询

函数	说明
cJSON_GetObjectItem(obj, key)	按 key 获取对象成员
cJSON_GetArraySize(arr)	获取数组长度
cJSON_GetArrayItem(arr, idx)	获取数组元素（0-based）
cJSON_GetStringValue(it)	获取字符串值
cJSON_GetNumberValue(it)	获取数值

创建

函数	说明
cJSON_CreateObject()	创建空对象 {}
cJSON_CreateArray()	创建空数组 []
cJSON_CreateString(s)	创建字符串节点
cJSON_CreateNumber(n)	创建数值节点
cJSON_CreateBool(b)	创建 true/false
cJSON_CreateNull()	创建 null

修改

函数	说明
cJSON_AddItemToObject(obj, key, item)	向对象添加键值对
cJSON_AddItemToArray(arr, item)	向数组追加元素
cJSON_DeleteItemFromObject(obj, key)	删除对象成员

序列化

函数	说明
cJSON_Print(node)	序列化为紧凑 JSON 字符串（调用者 free）

使用示例

#include "cJSON.h"
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    // --- 解析 JSON ---
    const char *json = "{\"name\":\"RTU\",\"addr\":1,\"items\":[1,2,3]}";
    stru_cjson *root = cJSON_Parse(json);

    const char *name = cJSON_GetStringValue(cJSON_GetObjectItem(root, "name"));
    double      addr = cJSON_GetNumberValue(cJSON_GetObjectItem(root, "addr"));

    printf("name=%s, addr=%.0f\n", name, addr);
    // 输出: name=RTU, addr=1

    // 遍历数组
    stru_cjson *arr = cJSON_GetObjectItem(root, "items");
    int n = cJSON_GetArraySize(arr);
    for (int i = 0; i < n; i++)
    {
        printf("  [%d] = %.0f\n", i,
               cJSON_GetNumberValue(cJSON_GetArrayItem(arr, i)));
    }

    cJSON_Delete(root);

    // --- 创建 JSON ---
    stru_cjson *obj = cJSON_CreateObject();
    cJSON_AddItemToObject(obj, "status", cJSON_CreateString("ok"));
    cJSON_AddItemToObject(obj, "code",   cJSON_CreateNumber(200));

    char *out = cJSON_Print(obj);
    printf("生成的 JSON: %s\n", out);  // {"status":"ok","code":200}
    free(out);
    cJSON_Delete(obj);

    return 0;
}

依赖关系

• 依赖: stdlib.h, string.h, stdio.h, math.h
• 被依赖: 配置文件解析、Web API 交互 等模块