对于嵌入式系统应用中，频繁使用的参数存储，过程变量存储等操作，AliOS-Things为用户提供了一种更加直观易于理解的基于键值对的存储方式，如报警温度=50度，可以通过定义一个键值对：{"AlarmTemp":50}来进行存储。获取时，也只需通过AlarmTemp这个关键字（键/KEY)即可快速获取和重新写入。KV将用户的指定片内flash扇区或eeprom虚拟为有一个存储空间，并且帮助用户管理键值对之间的映射关系，用户无需关心具体的值被写到哪里了，仅需要通过对键的操作即可完成数据的存取。

相对传统的读-修改-写的flash操作方式，KV服务将为用户提供近100倍的效率提升。

KV功能的相关源码位于：/core/kv/ 目录中。

API列表

aos_kv_set() 更新某个键的值，如果键不存在则创建一个新的键
aos_kv_get() 获取某个键的值
aos_kv_del() 删除键值对，删除后将不能访问也不能恢复
aos_kv_del_by_prefix() 以固定前缀删除键值对。如“Set_”
aos_kv_secure_set() 加密更新/创建某个键的值
aos_kv_secure_get() 获取某个加密的键的值

使用

添加该组件

kv系统是AliOS Things 默认添加的组件，开发者无需再手动添加。

包含头文件

#include <aos/aos.h>
#include "aos/kv.h"

使用示例

/* set wifi-ssid to aiot */
aos_kv_set("wifi-ssid", "aiot", 4, 1);

/* get wifi-ssid */
char buf[10] = {0};
int ret = 0;
int len = sizeof(buf);

ret = aos_kv_get("wifi-ssid", buf, &len);

API详情

KV的应用层API说明请参考core/kv/include/kv_api.h。

aos_kv_set()

更新某个键的值，如果键不存在则创建一个新的键。

函数原型

int aos_kv_set(const char *key, const void *value, int len, int sync);

输入参数

const char *key 需要操作的键的名称 “AlarmTemp”
const void *value 写入该键的值 50
int len 值的长度，字节为单位 1
int sync 同步写入标志，固定为1 1

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件

调用示例

static char *g_key_1 = "key_1";
static char *g_val_1 = "val_1";

int ret = 0;
ret = aos_kv_set(g_key_1, g_val_1, strlen(g_val_1),1);

aos_kv_get()

获取某个键的值。

函数原型

 int aos_kv_get(const char *key, void *buffer, int *buffer_len);

参数列表

const char *key 需要操作的键的名称 “AlarmTemp”
void *buffer 读取该键的值 50
int *buffer_len 返回实际值的长度，字节为单位 1

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件。

调用示例

static char *g_key_1 = "key_1";

int ret = 0;
char buf[10] = {0};
int len = sizeof(buf);

ret = aos_kv_get(g_key_1,buf,&len);

aos_kv_del()

删除键值对，删除后将不能访问也不能恢复。

函数原型

int aos_kv_del(const char *key);

参数列表

const char *key 需要操作的键的名称 “AlarmTemp”

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件。

调用示例

static char *g_key_1 = "key_1";

int ret = 0;

ret = aos_kv_del(g_key_1);

aos_kv_del_by_prefix()

以固定前缀删除键值对。如“Set_”。

函数原型

int aos_kv_del_by_prefix(const char *prefix);

参数列表

const char *prefix 需要删除的键的名称前缀 “Set_”

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件。

调用示例

static char *prefix = "Special_";

int ret = 0;

ret = aos_kv_del_by_prefix(prefix);

aos_kv_secure_set()

以加密的方式更新/创建某个键的值，使用该api需要在menuconfig配置选项中开启kv安全存储。

函数原型

int aos_kv_secure_set(const char *key, const void *value, int len, int sync);

参数列表

const char *key 需要操作的键的名称 “AlarmTemp”
const void *value 写入该键的值 50
int len 值的长度，字节为单位 1
int sync 同步写入标志，固定为1 1

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件。

调用示例

static char *g_key_1 = "key_1";
static char *g_val_1 = "val_1";

int ret = 0;
ret = aos_kv_secure_set(g_key_1, g_val_1, strlen(g_val_1),1);

aos_kv_secure_get()

获取某个加密的键的值，使用该api需要在menuconfig配置选项中开启kv安全存储。

函数原型

 int aos_kv_secure_get(const char *key, void *buffer, int *buffer_len);

参数列表

const char *key 需要操作的加密键的名称 “AlarmTemp”
void *buffer 读取该加密键的值 50
int *buffer_len 返回实际值的长度，字节为单位 1

返回参数

返回参数宏定义见core/kv/include/kv_api.h文件。

调用示例

static char *g_key_1 = "key_1";

int ret = 0;
char buf[10] = {0};
int len = sizeof(buf);

ret = aos_kv_secure_get(g_key_1,buf,&len);

配置说明

在AliOS Things 源码里面输入aos make menuconfig命令即可进入到menuconfig配置界面中，依次选择Kernel -> Key-Value Storage即可进入到KV组件的配置界面：

配置项说明

--- Key-value Storage
(32)   The garbage collection task priority             # KV垃圾回收任务（GC）的优先级，默认32
(1024) The garbage collection task stack size (bytes)   # KV垃圾回收任务（GC)）的栈大小，默认1024
(128)  The maximum length of key buffer (bytes)         # 一条KV的key存储大小，默认128(bytes)
(512)  The maximum length of value buffer (bytes)       # 一条KV的value存储大小，默认512(bytes)
[ ]    Key-value Storage Security Support               # 开启kv安全存储，默认不开启

移植说明

和KV相关的实现都在kv_adapt.c文件中，位于/core/kv/kv_adapt.c用户可以参考进行实现。

kv依赖AliOS Things的flash操作接口来实现kv存储功能。

其他

返回参数定义

返回参数定义在core/kv/include/kv_api.h文件中。

/* Key-value function return code description */
#define KV_OK                 0     /* Successed */
#define KV_LOOP_CONTINUE      10000 /* Loop Continue */
#define KV_ERR_NO_SPACE      -10001 /* The space is out of range */
#define KV_ERR_INVALID_PARAM -10002 /* The parameter is invalid */
#define KV_ERR_MALLOC_FAILED -10003 /* The os memory malloc error */
#define KV_ERR_NOT_FOUND     -10004 /* Could not found the item */
#define KV_ERR_FLASH_READ    -10005 /* The flash read operation error */
#define KV_ERR_FLASH_WRITE   -10006 /* The flash write operation error */
#define KV_ERR_FLASH_ERASE   -10007 /* The flash erase operation error */
#define KV_ERR_OS_LOCK       -10008 /* The error related to os lock */
#define KV_ERR_OS_SEM        -10009 /* The error related to os semaphose */

#define KV_ERR_ENCRYPT       -10010 /* Data encryption error */
#define KV_ERR_DECRYPT       -10011 /* Data decryption error */
#define KV_ERR_NOT_SUPPORT   -10012 /* The function is not support yet */