/**
 * @file hal_json.h
 * @brief JSON 解析/构建 HAL 接口
 */

#ifndef HAL_JSON_H
#define HAL_JSON_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/** JSON 对象句柄 */
typedef void *hal_json_t;

/**
 * @brief 解析 JSON 字符串
 * @return 句柄，失败返回 NULL
 */
hal_json_t hal_json_parse(const char *text);

/** @brief 创建空 JSON 对象 */
hal_json_t hal_json_create_object(void);

/**
 * @brief 按 key 获取字符串值
 * @return 字符串指针（生命周期随父对象），未找到返回 NULL
 */
const char *hal_json_get_string(hal_json_t json, const char *key);

/**
 * @brief 按 key 获取整数值
 * @return 0 成功，负值失败
 */
int hal_json_get_int(hal_json_t json, const char *key, int *out_value);

/**
 * @brief 按 key 获取数字的原始字符串形式
 *
 * 兼容 "key":123 和 "key":"123" 两种写法，仅复制十进制数字到 out。
 *
 * @return 写入字符数（不含 \0），失败返回负值
 */
int hal_json_get_number_string(hal_json_t json, const char *key,
                               char *out, size_t out_size);

/**
 * @brief 按 key 获取布尔值
 * @return 0 成功，负值失败
 */
int hal_json_get_bool(hal_json_t json, const char *key, bool *out_value);

/** @brief 添加字符串键值对 */
int hal_json_add_string(hal_json_t json, const char *key, const char *value);

/** @brief 添加整数键值对 */
int hal_json_add_int(hal_json_t json, const char *key, int value);

/** @brief 添加布尔键值对 */
int hal_json_add_bool(hal_json_t json, const char *key, bool value);

/**
 * @brief 按 key 获取子对象
 * @return 子对象句柄（生命周期随父对象），未找到返回 NULL
 */
hal_json_t hal_json_get_object(hal_json_t json, const char *key);

/**
 * @brief 按 key 获取数组
 * @return 数组句柄，未找到返回 NULL
 */
hal_json_t hal_json_get_array(hal_json_t json, const char *key);

/** @brief 获取数组元素个数 */
int hal_json_get_array_size(hal_json_t array);

/**
 * @brief 按索引获取数组元素
 * @return 元素句柄，越界返回 NULL
 */
hal_json_t hal_json_get_array_item(hal_json_t array, int index);

/**
 * @brief 序列化为字符串
 * @return JSON 字符串，需在 destroy 前使用或拷贝
 */
const char *hal_json_to_string(hal_json_t json);

/** @brief 销毁 JSON 对象 */
void hal_json_destroy(hal_json_t json);

#ifdef __cplusplus
}
#endif

#endif /* HAL_JSON_H */
