/* meow_settings.h — MeowOS 系统设置后端（阶段 B2a）
 *
 * 统一设置子系统：全部系统设置抽象为「名称/类型/默认/取值域」的扁平表，
 * 单点存板载 /usr/data/meow/settings.conf（UBIFS，KB 级小文件，key=value）。
 * 实体 UI / Web 面板 / CLI 均走本 API，不留旁路。
 *
 * 设计规范：SYSTEM_SETTINGS.md §1/§2/§3 + MEOWOS_API.md §2。
 * 返回码：MEOWOS_API.md §1（MEOW_OK=0，负值错误码）。
 * 注释风格：与 meow_launcherd 拆分层源码注释一致（中文注释 + 「M2.x 说明」格式）。
 *
 * 阶段 B2a 只建后端 + 核心 API；实体设置页(B2b)/Web 面板(C)后续复用。
 */
#ifndef MEOW_SETTINGS_H
#define MEOW_SETTINGS_H

#ifdef __cplusplus
extern "C" {
#endif

/* 统一错误码（MEOWOS_API.md §1；C 函数返回 int，0=成功，负=错误码） */
#ifndef MEOW_OK
#define MEOW_OK               0      /* 成功 */
#define MEOW_ERR_INVAL       -1      /* 参数/取值非法 */
#define MEOW_ERR_NOENT       -2      /* 键/资源不存在 */
#define MEOW_ERR_EXISTS      -3      /* 已存在（如重复注册） */
#define MEOW_ERR_PERM        -4      /* 无权限（本机信任模型下少用，保留） */
#define MEOW_ERR_IO          -5      /* 读写（存储/文件）失败 */
#define MEOW_ERR_NOMEM       -6      /* 内存不足 */
#define MEOW_ERR_NOTINIT     -7      /* 未初始化（如 settings 未 init） */
#define MEOW_ERR_BUSY        -8      /* 忙（如服务已运行） */
#define MEOW_ERR_TIMEOUT     -9      /* 超时 */
#define MEOW_ERR_NODEV       -10     /* 设备不存在（如无卡） */
#define MEOW_ERR_INTERNAL    -255    /* 内部错误 */
#endif /* MEOW_OK */

/* 字符串类型最大长度（set_str 截断；str 存取缓冲区建议为此值） */
#define MEOW_SET_MAX_LEN 256

/* 类型 schema：每个设置键注册“名称/类型/默认/取值域”，存取统一走表 */
typedef enum { SET_INT, SET_STR, SET_ENUM, SET_BOOL } meow_set_type;

/* 设置项注册描述（MEOWOS_API §2.7：新增设置照此；实体 UI/web/CLI 自动生成控件） */
typedef struct meow_setting_def {
    const char *key;           /* 如 "display.brightness" */
    meow_set_type type;
    const char *def;           /* 默认值字符串（int/str/enum/bool 统一字符串） */
    int min, max;              /* SET_INT 取值域（max<=0 表示仅保底、无上界）；其他 0 */
    const char *enum_names;    /* SET_ENUM：逗号分隔选项名，如 "panel,black" */
    const char *enum_labels;   /* 对应中文标签，如 "面板下电,背光全黑双击" */
} meow_setting_def;

/* 变更通知回调：key 变化时调用（实体 UI 据此重绘 / web 经 MeowPanel 推送） */
typedef void (*meow_settings_listener)(const char *key);

/* ---- 初始化/生命周期 ---- */
/* 加载 storage + 注册默认；幂等，可重载（重载=重置默认再读 settings.conf）。
 * 返回 MEOW_OK / MEOW_ERR_IO（文件可读性）/ MEOW_ERR_NOMEM（表满）。 */
int  meow_settings_init(void);
/* 保存 + 清理（进程退出前调；不自动调用） */
int  meow_settings_shutdown(void);
/* 调试：打印当前全部键（前缀 + key = value） */
void meow_settings_dump(const char *log_prefix);

/* ---- 设置项注册（启动时批量注册；重复注册返回 MEOW_ERR_EXISTS）---- */
int  meow_settings_register(const meow_setting_def *def);

/* ---- 类型化存取（get 返回 0=成功，负=错误码；set 含 clamp/校验 + 广播）---- */
int  meow_settings_get_int (const char *key, int *out);
int  meow_settings_get_str (const char *key, char *buf, int buf_len);
int  meow_settings_get_enum(const char *key, int *out);   /* 返回索引（名字->索引） */
int  meow_settings_get_bool(const char *key, int *out);   /* 0/1 */

/* M2.53：返回当前用户亮度设定（display.brightness）经 clamp_brightness 后的值
 * （下限 display.brightness_min 默认 1=极暗但可见、上限 100=防闪屏）。
 * MeowOS 主屏接管时用它把亮度压回用户值，覆盖 HibyOS 播放器写入的背光下限 16/25。
 * settings 未初始化/键缺失时回退默认 101 再 clamp（→100）；纯函数，宿主机可直接测。 */
int  meow_settings_brightness_clamped(void);

int  meow_settings_set_int (const char *key, int v);        /* clamp 到取值域 */
int  meow_settings_set_str (const char *key, const char *v);/* 长度截断 MEOW_SET_MAX_LEN */
int  meow_settings_set_enum(const char *key, int idx);      /* 校验枚举合法，越界拒绝 */
int  meow_settings_set_bool(const char *key, int v);

/* M2.5x：开关型键的通用读写。开关 = SET_BOOL，或 SET_INT 且取值域恰为 {0,1}
 * （如 display.multi_font / font.load_full，二者按 SYSTEM_SETTINGS §1 用 int 0/1 存储）。
 * 实体设置页 SC_SWITCH 控件与字体逻辑统一走本对接口——若对这些 SET_INT 开关误用
 * get_bool/set_bool，类型不符（SET_BOOL 才接受）必返回 MEOW_ERR_INVAL，导致开关
 * 「点不动/恒 OFF/多字体 6 类行恒隐藏」。返回值语义同其它 get 系列 / set 系列。 */
int  meow_settings_get_switch(const char *key, int *out);   /* 0/1；SET_BOOL 或 SET_INT 0/1 */
int  meow_settings_set_switch(const char *key, int v);      /* 同上；写入 clamp 并广播 */

/* ---- 变更通知（set 成功后广播 key 字符串）---- */
int  meow_settings_add_listener(meow_settings_listener cb);
int  meow_settings_remove_listener(meow_settings_listener cb);

/* ---- 枚举辅助（供 UI/web 显示中文标签）---- */
int  meow_settings_enum_label(const char *key, int idx, char *buf, int buf_len);
int  meow_settings_enum_count(const char *key);              /* 选项数；错误负值 */
int  meow_settings_enum_index_of_name(const char *key, const char *name);
void meow_settings_enum_names(const char *key, const char **out_names, int *n);

/* ---- 列表：枚举当前全部键，供 web 面板 / 设置页生成控件 ---- */
int  meow_settings_list(int (*cb)(const char *key, meow_set_type t, void *ctx), void *ctx);

/* ---- 默认值 / 复位 ---- */
int  meow_settings_get_default(const char *key, char *buf, int len);
int  meow_settings_reset(const char *key);   /* 单键复位默认 */
int  meow_settings_reset_all(void);          /* 全量复位 */

/* ---- 落盘 / 导入导出（备份）---- */
int  meow_settings_save(void);   /* 写板载 settings.conf，保留 "# meow-settings 1" 头 */
int  meow_settings_export(const char *path);   /* 写一份 .conf 到 path；NULL=默认 TF 卡备份路径 */
int  meow_settings_import(const char *path);   /* 从 .conf 读入覆盖；逐键校验，记录损坏键不中断 */

#ifdef __cplusplus
}
#endif
#endif /* MEOW_SETTINGS_H */