119 lines
3.2 KiB
Markdown
119 lines
3.2 KiB
Markdown
# libcJSON — JSON 解析/生成库 API 参考
|
||
|
||
## 模块概述
|
||
|
||
libcJSON 是开源的轻量级 JSON 解析/生成库（MIT 许可证），直接使用原工程版本。
|
||
基于递归下降解析器 + 树状内存模型。支持 object/array/string/number/boolean/null。
|
||
|
||
## 数据结构
|
||
|
||
```c
|
||
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） |
|
||
|
||
## 使用示例
|
||
|
||
```c
|
||
#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 交互 等模块
|