1 /*
2  * Copyright (C) 2017-2021 Alibaba Group Holding Limited
3  */
4 
5 #ifndef AOS_KV_H
6 #define AOS_KV_H
7 
8 #include <aos/kernel.h>
9 #include <string.h>
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /** @defgroup kv_aos_api kv
16  * @{
17  */
18 
19 /**
20  * Init the kv module.
21  *
22  * @retrun 0 on success, otherwise will be failed.
23  */
24 int aos_kv_init(void);
25 
26 /**
27  * Deinit the kv module.
28  *
29  * @retrun none
30  */
31 void aos_kv_deinit(void);
32 
33 /**
34  * Add a new KV pair.
35  *
36  * @param[in]  key    the key of the KV pair.
37  * @param[in]  value  the value of the KV pair.
38  * @param[in]  len    the length of the value.
39  * @param[in]  sync   save the KV pair to flash right now (should always be 1).
40  *
41  * @return  0 on success, negative error on failure.
42  */
43 int aos_kv_set(const char *key, const void *value, int len, int sync);
44 
45 /**
46  * Get the KV pair's value stored in buffer by its key.
47  *
48  * @note: the buffer_len should be larger than the real length of the value,
49  *        otherwise buffer would be NULL.
50  *
51  * @param[in]      key         the key of the KV pair to get.
52  * @param[out]     buffer      the memory to store the value.
53  * @param[in-out]  buffer_len  in: the length of the input buffer.
54  *                             out: the real length of the value.
55  *
56  * @return  0 on success, negative error on failure.
57  */
58 int aos_kv_get(const char *key, void *buffer, int *buffer_len);
59 
60 /**
61  * Delete the KV pair by its key.
62  *
63  * @param[in]  key  the key of the KV pair to delete.
64  *
65  * @return  0 on success, negative error on failure.
66  */
67 int aos_kv_del(const char *key);
68 
69 /**
70  * Delete the KV pair by its prefix.
71  *
72  * @param[in]  prefix  the prefix of the kv pair which is need to delete.
73  *
74  * @return  0 on success, negative error on failure.
75  */
76 int aos_kv_del_by_prefix(const char *prefix);
77 
78 /**
79  * Add a new KV pair with encryption.
80  *
81  * @param[in]  key    the key of the KV pair.
82  * @param[in]  value  the value of the KV pair.
83  * @param[in]  len    the length of the value.
84  * @param[in]  sync   save the KV pair to flash right now (should always be 1).
85  *
86  * @return  0 on success, negative error on failure.
87  */
88 int aos_kv_secure_set(const char *key, const void *value, int len, int sync);
89 
90 /**
91  * Get the KV pair's value stored in buffer by its key with decrypt.
92  *
93  * @note: the buffer_len should be larger than the real length of the value,
94  *        otherwise buffer would be NULL.
95  *
96  * @param[in]      key         the key of the KV pair to get.
97  * @param[out]     buffer      the memory to store the value.
98  * @param[in-out]  buffer_len  in: the length of the input buffer.
99  *                             out: the real length of the value.
100  *
101  * @return  0 on success, negative error on failure.
102  */
103 int aos_kv_secure_get(const char *key, void *buffer, int *buffer_len);
104 
105 /**
106  * @}
107  */
108 
109 #ifdef __cplusplus
110 }
111 #endif
112 
113 #endif /* AOS_KV_H */
114