黑暗模式
如何存取应用程序的配置信息
1. 介绍
AWTK 提供了 app_conf 接口，用于保存或读取应用程序的配置信息。其特点有：
- 线程安全，可以多线程访问。
- 观察者模式，配置变化时通知关注者。
- 统一接口，不用关注存储格式和存储介质。
- 接口支持多种数据类型，开发者无需在字符串和其它类型之间转换。
配置信息可以保存为任意格式，目前支持下列文件格式（其它格式开发者可以自行增加）:
配置信息可以存放在任何介质上，目前支持以下介质：
文件系统。
Flash(TODO)
2. 初始化（任意选一种格式即可）
app_conf 作为可选组件，需要开发者自己初始化。
初始化函数一般在 application_init 函数中调用。所有读写等函数，必须在成功初始化之后才能调用。
配置文件通常保存在用户目录下，比如应用程序的名称为demo，存储格式为json，那么在不同的平台下，存放的位置为：
- linux
～/demo/app_conf.json- macos
～/demo/app_conf.json- windows
～/AppData/Local/demo/app_conf.json- 嵌入式
/appdata/demo/app_conf.json应用程序在启动时，会打印配置文件的位置，以实际位置为准。
- 2.1 使用 ini 格式时的初始方法
包含头文件：
c
#include "conf_io/app_conf_init_ini.h"调用初始化函数
c
/**
* @method app_conf_init_ini
*
* 初始化应用程序的配置信息。
*
* @param {const char*} app_name 应用程序名称。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_init_ini(const char* app_name)示例：
c
ENSURE(app_conf_init_ini("demo") == RET_OK);- 2.2 使用 json 格式时的初始方法
包含头文件：
c
#include "conf_io/app_conf_init_json.h"调用初始化函数
c
/**
* @method app_conf_init_json
*
* 初始化应用程序的配置信息。
*
* @param {const char*} app_name 应用程序名称。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_init_json(const char* app_name)示例：
c
ENSURE(app_conf_init_json("demo") == RET_OK);- 2.3 使用 ubjson 格式时的初始方法
包含头文件：
c
#include "conf_io/app_conf_init_ubjson.h"调用初始化函数
c
/**
* @method app_conf_init_ubjson
*
* 初始化应用程序的配置信息。
*
* @param {const char*} app_name 应用程序名称。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_init_ubjson(const char* app_name)示例：
c
ENSURE(app_conf_init_ubjson("demo") == RET_OK);3. 存取配置信息
3.1 包含头文件：
app_conf 作为可选组件，需要开发者自己包含头文件。
c
#include "conf_io/app_conf.h"3.2 修改配置信息
c
/**
* @method app_conf_set_int
* 设置整数类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {int32_t} v 配置项的值。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_set_int(const char* key, int32_t v);
/**
* @method app_conf_set_int64
* 设置 64 位整数类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {int64_t} v 配置项的值。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_set_int64(const char* key, int64_t v);
/**
* @method app_conf_set_bool
* 设置 bool 类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {bool_t} v 配置项的值。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_set_bool(const char* key, bool_t v);
/**
* @method app_conf_set_double
* 设置双精度类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {double} v 配置项的值。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_set_double(const char* key, double v);
/**
* @method app_conf_set_str
* 设置字符串类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {const char*} v 配置项的值。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_set_str(const char* key, const char* v);示例：
c
app_conf_set_bool("wifi.on", TRUE);
app_conf_set_str("wifi.name", "awtk");
app_conf_set_int("server.port", 8080);
app_conf_set_double("server.timeout", 1.0);使用 ini 格式时，实际存为：
ini
[wifi]
on = 1
name = awtk
[server]
port = 8080
timeout = 1.000000使用 json 格式时，实际存为：
ini
{
"wifi" : {
"on" : true,
"name" : "awtk"
},
"server" : {
"port" : 8080,
"timeout" : 1
}
}使用 ubjson 格式时，实际存为二进制格式，这里不再举例。
3.3 读取配置信息
c
/**
* @method app_conf_get_int
* 获取整数类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {int32_t} defval 缺省值。
*
* @return {int32_t} 返回配置项的值（如果不存在返回缺省值）。
*/
int32_t app_conf_get_int(const char* key, int32_t defval);
/**
* @method app_conf_get_int64
* 获取 64 位整数类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {int64_t} defval 缺省值。
*
* @return {int64_t} 返回配置项的值（如果不存在返回缺省值）。
*/
int64_t app_conf_get_int64(const char* key, int64_t defval);
/**
* @method app_conf_get_bool
* 获取 bool 类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {bool_t} defval 缺省值。
*
* @return {bool_t} 返回配置项的值（如果不存在返回缺省值）。
*/
bool_t app_conf_get_bool(const char* key, bool_t defval);
/**
* @method app_conf_get_double
* 获取单精度浮点数类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {double} defval 缺省值。
*
* @return {double} 返回配置项的值（如果不存在返回缺省值）。
*/
double app_conf_get_double(const char* key, double defval);
/**
* @method app_conf_get_str
* 获取字符串类型配置项的值。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
* @param {const char*} defval 缺省值。
*
* @return {const char*} 返回配置项的值（如果不存在返回缺省值）。
*/
const char* app_conf_get_str(const char* key, const char* defval);示例：
c
on = app_conf_get_bool("wifi.on", FALSE);
port = app_conf_get_int("server.port", 0);
timeout = app_conf_get_double("server.timeout", 0);
name = app_conf_get_str("wifi.name", NULL);3.4 删除配置信息
c
/**
* @method app_conf_remove
* 删除配置项。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_remove(const char* key);示例：
c
app_conf_set_str("wifi.password", "123123");
assert(app_conf_exist("wifi.password"));
app_conf_remove("wifi.password");
assert(!app_conf_exist("wifi.password"));3.5 检查配置信息是否存在
c
/**
* @method app_conf_exist
* 检查配置项是否存在。
*
* @annotation ["static", "scriptable"]
*
* @param {const char*} key 配置项的名称。
*
* @return {bool_t} 返回 TRUE 表示存在，FALSE 表示不存在。
*/
bool_t app_conf_exist(const char* key);示例：
c
app_conf_set_str("wifi.password", "123123");
assert(app_conf_exist("wifi.password"));
app_conf_remove("wifi.password");
assert(!app_conf_exist("wifi.password"));3.6 持久保存配置信息
c
/**
* @method app_conf_save
* 持久保存配置。
*
* @annotation ["static", "scriptable"]
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_save(void);示例：
c
app_conf_save();3.7 关注配置信息的变化
c
/**
* @method app_conf_on_changed
* 注册配置变化事件。
*
* @annotation ["static", "scriptable"]
* @param {event_func_t} on_event 事件处理函数。
* @param {void*} ctx 事件处理函数上下文。
* @return {uint32_t} 返回 id，用于 app_conf_off_changed。
*/
uint32_t app_conf_on_changed(event_func_t on_event, void* ctx);
/**
* @method app_conf_off_changed
* 注销配置变化事件。
*
* @annotation ["static", "scriptable"]
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_off_changed(uint32_t id);
/**
* @method app_conf_off_changed_by_ctx
* 注销配置变化事件。
*
* @annotation ["static"]
* @param {void*} ctx 事件处理函数上下文。
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_off_changed_by_ctx(void* ctx);示例：
c
static ret_t app_conf_changed(void* ctx, event_t* e) {
prop_change_event_t* evt = prop_change_event_cast(e);
log_debug("%s changed\n", evt->name);
return RET_OK;
}
...
app_conf_on_changed(app_conf_changed, NULL);回调函数在修改配置的线程调用。如果是后台线程修改配置，在配置变化时，需要更新界面，此时需要用 idle_queue 进行串行化。
3.8 恢复出厂设置
用默认配置文件替换当前配置文件，并重新加载。
c
/**
* @method app_conf_reset
*
* 恢复出厂设置。
*
* @annotation ["global"]
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t app_conf_reset(void);6. 释放配置相关资源。
c
/**
* @method app_conf_deinit
* 释放 conf 对象。
*
* @annotation ["static", "scriptable"]
*
* @return {ret_t} 返回 RET_OK 表示成功，否则表示失败。
*/
ret_t app_conf_deinit(void);示例：
c
ret_t application_exit() {
app_conf_deinit();
log_debug("application_exit\n");
return RET_OK;
}7. key 的规则
- 配置信息通常都是层次结构的，为了能访问所有数据，key 也必须是多级的，各级的名称之间用“.”分隔。
“.”不能作为名称的一部分，如果出现，需要用其它字符代替。
json
{
"network" : {
"eth0" : {
"ip" : "192.169.0.100",
"gateway" : "192.169.0.1",
"mask" : "255.255.255.0"
}
}
}在这个例子中，要访问 ip 的这个配置，可以用"network.eth0.ip":
c
app_conf_set_str("network.eth0.ip", "192.169.0.100");- 按索引访问
在访问时，每一级的名称，可以用索引代替，格式为：[+索引+]，比如 [0] 表示第一项，[2] 表示第三项。这对于不清楚名称的情况，或遍历全部配置，很有帮助。
如：
c
const char* ip0 = app_conf_get_str("network.[0].ip", NULL);
const char* ip1 = app_conf_get_str("network.[1].ip", NULL);
const char* ip2 = app_conf_get_str("network.[2].ip", NULL);- 用 #size 获取子节点个数
示例：
ini
[wifi]
on = 1
name = awtk
[server]
port = 8080
timeout = 1.000000在上面的例子中，"#size"获取分组的个数为 2，"wifi.#size"获取 wifi 下的子项数为 2。
c
assert(app_conf_get_int("#size", 0) == 2);
assert(app_conf_get_int("wifi.#size", 0) == 2);- 用 #name 获取项的名称。
示例：
ini
[wifi]
on = 1
name = awtk
[server]
port = 8080
timeout = 1.000000在上面的例子中，"[0].#name" 获取第一个分组的名称为"wifi"，"wifi.[0].#name" 获取 wifi 下第一项的名称为 "on"。
c
assert(strcmp(app_conf_get_str("[0].#name", NULL), "wifi") == 0);
assert(strcmp(app_conf_get_str("wifi.[0].#name", NULL), "on") == 0);- 用 #index 获取配置项在兄弟节点中的序数。
ini
[wifi]
on = 1
name = awtk
[server]
port = 8080
timeout = 1.000000在上面的例子中，"wifi.#index" 获取 wifi 的序数为 0，"server.#index" 获取 server 的序数为 1。
c
assert(app_conf_get_int("wifi.#index", -1) == 0);
assert(app_conf_get_int("server.#index", -1) == 1);8. 缺省配置
位置。缺省配置放到资源中，位于：design/default/data
命名：应用程序名 + '.' + 文件扩展名。
文件扩展名与初始化时指定的格式一致。
比如，下面的例子中，应用程序名 demo，扩展名为 json。所以对应的缺省配置文件为：design/default/demo.json
c
ENSURE(app_conf_init_json("demo") == RET_OK);在初始化时，如果配置文件不存在，则将缺省配置拷贝到配置文件。
9. 注意事项
英文的点(.) 作为 key 的分隔符，所以 key 不能包含英文的点(.)。
ini 格式不支持注释和换行。