125 lines
7.1 KiB
C
125 lines
7.1 KiB
C
/* 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);
|
||
|
||
/* M2.86：settings.conf 是否真正从盘上读到过（最近一次 meow_settings_init 成功打开文件）。
|
||
* 0 = S70 早启动 /usr/data 未就绪 fopen 失败 → 当前全为默认值（display.brightness 101→clamp 100），
|
||
* 调用方（尤其 apply_user_brightness）不得把默认值当作用户设定写入，应挂起待设置就绪再补应用；
|
||
* 1 = 文件已读到：键缺失走各自默认（属「已知」态），用户设定可信。 */
|
||
int meow_settings_loaded(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 */
|