# 接口说明文档

## 接口

[TOC]

### new

> 声明
>
> ```C
> KSettings *kdk_conf2_new (
>  	const char 	*id,
>  	const char 	*version
> )
> ```

> 描述
>
> ​	读取指定id指定版本的句柄。

> 参数
>
> ​	id :	组的路径
>
> ​	version： 版本号
>
> ​		传NULL，使用配置文件内设置默认版本
>
> ​		如果配置文件内没有设置默认版本，取最高版本为默认版本

> 返回值
>
> ​	指定id的配置句柄，失败返回NULL
>
> ​	调用方获得句柄的所有权，并负责释放数据

### destroy

> 声明
>
> ```C
> void kdk_conf2_ksettings_destory(
>      KSettings 	*ksettings
> )
> ```

> 描述
>
> ​	销毁由kdk_conf2_new取得的配置句柄

> 参数
>
> ​	ksettings:	由kdk_conf2_new获取的句柄

>返回
>
>​	无

### get_id

> 声明
>
> ```C
> char *
> kdk_conf2_get_id(
> 	KSettings 	*settings
> )
> ```

> 描述
>
> ​	获取配置句柄对应的配置id

> 参数
>
> ​	settings:	句柄

> 返回值
>
> ​	配置id
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据

### get_version

> 声明
>
> ```C
> char *
> kdk_conf2_get_version(
> 	KSettings 	*settings
> )
> ```

> 描述
>
> ​	获取配置句柄对应的配置版本

> 参数
>
> ​	settings:	句柄

> 返回值
>
> ​	配置版本号
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据

### get_child

> 声明
>
> ```C
> KSettings *
> kdk_conf2_get_child (
> 	KSettings 	*ksettings，   
> 	const char 	*name
> )
> ```

> 描述
>
> ​	获取当前句柄子id的配置句柄

> 参数
>
> ​	ksettings：  配置句柄
>
> ​	name： 子组名

> 返回值
>
> ​	子id句柄，失败返回NULL
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据

### list_children

> 声明
>
> ```C
> char **
> kdk_conf2_list_children (
> 	KSettings 	*ksettings  
> )
> ```

> 描述
>
> ​	获取当前句柄所有子组的名称

> 参数
>
> ​	ksettings： 句柄

> 返回值
>
> ​	以NULL结尾的字符串数组
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。
>
> ​	获取失败返回NULL

### list_keys

> 声明
>
> ```C
> char **
> kdk_conf2_list_keys (
> 	KSettings 	*ksettings
> )
> ```

> 描述
>
> ​	获取当前句柄所有的键名

> 参数
>
> ​	settings： 句柄

> 返回值
>
> ​	以NULL结尾的字符串数组
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。
>
> ​	获取失败返回NULL

### get_boolean

> 声明
>
> ```C
> int
> kdk_conf2_get_boolean (
>     	KSettings 	*ksettings,   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`bool`类型的键的值。
>
> ​	调用方调用此接口时需确认键值确为`bool`类型

> 参数
>
> ​	settings:	句柄
>
> ​	key： 键名

> 返回值
>
> ​	布尔值 
>
> ​	1：True
>
> ​	0：False

### get_default_value

> 声明
>
> ```C
> char *
> kdk_conf2_get_default_value (
>     	KSettings 	*ksettings,   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中键的默认值

> 参数
>
> ​	ksettings： 句柄
>
> ​	key： 键名

> 返回值
>
> ​	符合配置类型标签的字符串，失败返回NULL
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_double

> 声明
>
> ```C
> double
> kdk_conf2_get_double (
>     	KSettings 	*ksettings,   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`double`类型的键的值
>
> ​	调用方需确认键值确为`double`类型

> 参数
>
> ​	ksettings： 句柄
>
> ​	key： 键名

> 返回值
>
> ​	浮点型值

### get_enum

> 声明
>
> ```C
> int
> kdk_conf2_get_enum (
>     	KSettings 	*ksettings,   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`enum`类型的键的值
>
> ​	调用方请确认键值类型确为`emum`类型

> 参数
>
> ​	ksettings:	句柄
>
> ​	key： 键名

> 返回值
>
> ​	枚举的值，类型为`int`型

### get_int

> 声明
>
> ```C
> int
> kdk_conf2_get_int (
>     	KSettings 	*ksettings,  
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`int`类型的键的值
>
> ​	调用方请确认键值确为`int`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	整型值

### get_int64

> 声明
>
> ```C
> long
> kdk_conf2_get_int (
>     	KSettings 	*ksettings,  
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`int64`类型的键的值
>
> ​	调用方请确认键值确为`int64`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	长整型数值

### get_range

> 声明
>
> ```C
> char *
> kdk_conf2_get_range (
>     	KSettings 	*ksettings，  
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中键的取值范围

> 参数
>
> ​	ksettings:	句柄
>
> ​	key：	键名

> 返回值
>
> ​	取值范围，不存在取值范围返回NULL
>
> ​	针对枚举类型，返回`"a{si}"`类型的字符串
>
> ​	针对取值区间，返回`“min,max”`类型的字符串
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_string

> 声明
>
> ```C
> char *
> kdk_conf2_get_string (
>     	KSettings 	*ksettings，   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`string`类型的键值
>
> ​	调用方请确认键值的确为`string`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	字符串，失败返回NULL
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_strv

> 声明
>
> ```C
> char **
> kdk_conf2_get_strv (
>     	KSettings 	*ksettings，   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`strv`类型的键值
>
> ​	调用方请确认键值确为`strv`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	以NULL结尾的字符串数组，失败返回NULL
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_uint

> 声明
>
> ```C
> unsigned int
> kdk_conf2_get_uint (
>     	KSettings 	*ksettings,   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`uint`类型的键值
>
> ​	调用方请确认键值确为`uint`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	无符号整型值

### get_uint64

> 声明
>
> ```C
> unsigned long
> kdk_conf2_get_uint64 (
>     	KSettings 	*ksettings,  
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中`uint64`类型的键值
>
> ​	调用方请确认键值的确为`uint64`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	无符号长整型值

### get_value

> 声明
>
> ```C
> char *
> kdk_conf2_get_value (
>     	KSettings 	*ksettings，   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取设置中键的值

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	符合键值类型标签的字符串，失败返回NULL
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_description

> 声明
>
> ```C
> char *
> kdk_conf2_get_description (
>     	KSettings 	*ksettings，   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取键的`description`字段

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	键的`descritpion`字段
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据。

### get_summary

> 声明
>
> ```C
> char *
> kdk_conf2_get_summary(
> 	KSettings 	*settings,
> 	const char 	*key
> )
> ```

> 描述
>
> ​	获取键的`summary`字段

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名

> 返回值
>
> ​	键的`summary`字段
>
> ​	该方法的调用方取得数据的所有权，并负责释放数据

### is_writable

> 声明
>
> ```C
> int
> kdk_conf2_is_writable (
>     	KSettings 	*ksettings，   
> 	const char 	*key
> )
> ```

> 描述
>
> ​	检测键值是否可写

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key： 键名

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False



### range_check

> 声明
>
> ```C
> int
> kdk_conf2_range_check (
>     	KSettings	*settings,
> 	const char 	*key,
> 	const char 	*value
> )
> ```

> 描述
>
> ​	检查要设置值是否在取值区间

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名 应该存在取值区间或是枚举类型
>
> ​	value：	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1： True
>
> ​	0： False

### reset

> 声明
>
> ```C
> void
> kdk_conf2_reset (
>     	KSettings 	*settings,
> 	const char 	*key
> )
> ```

> 描述
>
> ​	将键的值重制为默认值

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名

> 返回值
>
> ​	无

### reload

> 声明
>
> ```C
> void
> kdk_conf2_reload ();  
> ```

> 描述
>
> ​	重新读取配置文件，并与当前用户的配置合并

> 参数
>
> ​	无

> 返回值
>
> ​	无

### set_boolean

> 声明
>
> ```C
> int
> kdk_conf2_set_boolean(
>     	KSettings	*settings, 
>     	const char 	*key, 
>     	int 		 value
>    ) 
> ```

> 描述
>
> ​	设置`bool`类型的键值
>
> ​	调用方请确认键值确为`bool`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value：	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_double

> 声明
>
> ```C
> int
> kdk_conf2_set_double(
>     	KSettings 	*ksettings， 
>     	const char 	*key, 
>     	double 		 value
>    ) 
> ```

> 描述
>
> ​	设置`double`类型的键值
>
> ​	调用方请确认键值确为`double`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_enum

> 声明
>
> ```C
> int
> kdk_conf2_set_enum(
>     	KSettings 	*settings， 
>     	const char 	*key, 
>     	int 		 value
>    ) 
> ```

> 描述
>
> ​	设置`enum`类型的键值
>
> ​	调用方请确认键值存在于`enum`中

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_int

> 声明
>
> ```C
> int
> kdk_conf2_set_int(
>     KSettings 	*settings, 
>     const char *key, 
>     int 		 value
>    ) 
> ```

> 描述
>
> ​	设置`int`类型的键值
>
> ​	调用方请确认键值类型确为`int`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_int64

> 声明
>
> ```C
> int
> kdk_conf2_set_int64(
>         KSettings 	*ksettings, 
>         const char *key, 
>         long 		 value
>    ) 
> ```

> 描述
>
> ​	设置`int64`类型的键值
>
> ​	调用方请确认键值类型确为`int64`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_string

> 声明
>
> ```C
> int
> kdk_conf2_set_string(
>     Ksettings 	*ksettings, 
>     const char *key, 
>     const char *value
>    ) 
> ```

> 描述
>
> ​	设置`char *`类型的键值
>
> ​	调用方请确认键值类型确为`char *`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_strv

> 声明
>
> ```C
> int
> kdk_conf2_set_strv(
>     KSettings 			*ksettings, 
>     const char 		*key, 
>     const char *const	*value
>    ) 
> ```

> 描述
>
> ​	设置`char **`类型的键值
>
> ​	调用方请确认键值类型确为`char **`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_uint

> 声明
>
> ```C
> int
> kdk_conf2_set_uint(
>     KSettings 		*ksettings, 
>     const char 	*key, 
>     unsigned int 	 value
>    ) 
> ```

> 描述
>
> ​	设置`uint`类型的键值
>
> ​	调用方请确认键值类型确为`uint`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_uint64

> 声明
>
> ```C
> int
> kdk_conf2_set_uint64(
>     KSettings 		*ksettings, 
>     const char 	*key, 
>     unsigned long 	 value
>    ) 
> ```

> 描述
>
> ​	设置`uint64`类型的键值
>
> ​	调用方请确认键值类型确为`uint64`类型

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	要设置的值

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### set_value

> 声明
>
> ```C
> int
> kdk_conf2_set_value(
>     KSettings 	*ksettings, 
>     const char *key, 
>     const char *value
>    ) 
> ```

> 描述
>
> ​	设置键值

> 参数
>
> ​	ksettings: 	句柄
>
> ​	key:	键名
>
> ​	value:	符合配置项类型标签的键值字符串

> 返回值
>
> ​	布尔值
>
> ​	1: True
>
> ​	0: False

### connect_signal

> 声明
>
> ```C
> unsigned long
> kdk_conf2_connect_signal(
>  KSettngs 	*ksettings,
>  const char *signal_name,
>  KCallBack	 handler,
>    void		*user_data
> )
> typedef void (*KCallBack) (void);
> ```

> 描述
>
> ​	注册回调函数以相应键值改变信号

> 参数
>
> ​	ksettings:	信号链接的对象
>
> ​	signal_name:	信号的详细描述，格式"signal-name::detailed". 例如"changed"或"changed::key"
>
> ​	handler:	信号处理函数的C函数指针
>
> ​	user_data:	传递给信号处理函数的用户数据

> 返回
>
> ​	信号处理函数的ID，销毁句柄时会自动销毁句柄绑定的信号处理ID

### list-shcemas

> 声明
>
> ```c
> char**
> kdk_conf2_list_schemas(
>  const char	*app,
>  const char	*version
> )
> ```

> 描述
>
> ​	查看指定应用拥有的所有schema id。可指定版本，不指定则读取默认版本

> 参数
>
> ​	app： 应用名
>
> ​	version： 版本号，可以传NULL

> 返回
>
> ​	成功返回id列表， 失败返回NULL

### save

> 声明
>
> ```c
> int
> kdk_conf2_save_user_configure(
>  const char	*path
> )
> ```

> 描述
>
> ​	将数据库中的用户配置导出为配置文件，存放到目标路径

> 参数
>
> ​	path： 目标路径，请确定有写权限

> 返回
>
> ​	成功返回1， 失败返回0

## 信号

### changed

> 声明
>
> ```C
> void
> changed(
> 	KSettings 	*传递给信号处理函数的用户数据,
> 	char 	  	*key,
> 	void	  	*user_data
> )
> ```
>
> 

> 描述
>
> ​	"changed"信号会在配置的设置值被修改时发出，您应该调用kdk_conf2_get()系列接口来获取新值。
>
> ​	该信号支持详细链接,可以连接到详细信号"changed::detailed",增加"detailed"修饰符可以仅在键"detailed"更改时接收回调。
>
> ​	注意，只有在信号已连接且您至少读取过一次配置时，这个信号才会发出。
>
> ​	回调函数：
>
> ​	使用`kdk_conf2_connect_signal()`注册"changed"信号的回调函数

> 参数
>
> ​	key： 被更改的键名

### update

> 声明
>
> ​	updated() -> ()

> 描述
>
> ​	在对配置进行reload动作后，发送此信号

> 参数
>
> ​	无