Mbed OS Reference
Loading...
Searching...
No Matches
KVStore.h
1/*
2 * Copyright (c) 2018 ARM Limited. All rights reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 * Licensed under the Apache License, Version 2.0 (the License); you may
5 * not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef MBED_KVSTORE_H
18#define MBED_KVSTORE_H
19
20#include <stdint.h>
21#include <stdio.h>
22#include <string.h>
23
24namespace mbed {
25
26/**
27 * \addtogroup storage
28 * @{
29 * \defgroup kvstore KVStore
30 * Classes for key-value storage.
31 * @{
32 */
33
34/** KVStore class
35 *
36 * Interface class for all Key Value Storage providers.
37 */
38class KVStore {
39public:
40 enum create_flags {
41 WRITE_ONCE_FLAG = (1 << 0),
42 REQUIRE_CONFIDENTIALITY_FLAG = (1 << 1),
43 RESERVED_FLAG = (1 << 2),
44 REQUIRE_REPLAY_PROTECTION_FLAG = (1 << 3),
45 };
46
47 static const uint32_t MAX_KEY_SIZE = 128;
48
49 typedef struct _opaque_set_handle *set_handle_t;
50
51 typedef struct _opaque_key_iterator *iterator_t;
52
53 /**
54 * Holds key information
55 */
56 typedef struct info {
57 /**
58 * The key size
59 */
60 size_t size;
61 /*
62 * The Key flags, possible flags combination:
63 * WRITE_ONCE_FLAG,
64 * REQUIRE_CONFIDENTIALITY_FLAG,
65 * REQUIRE_REPLAY_PROTECTION_FLAG
66 */
67 uint32_t flags;
69
70 virtual ~KVStore() {};
71
72 /**
73 * @brief Initialize KVStore
74 *
75 * @returns MBED_SUCCESS on success or an error code on failure
76 */
77 virtual int init() = 0;
78
79 /**
80 * @brief Deinitialize KVStore
81 *
82 * @returns MBED_SUCCESS on success or an error code on failure
83 */
84 virtual int deinit() = 0;
85
86
87 /**
88 * @brief Reset KVStore contents (clear all keys)
89 *
90 * @returns MBED_SUCCESS on success or an error code on failure
91 */
92 virtual int reset() = 0;
93
94 /**
95 * @brief Set one KVStore item, given key and value.
96 *
97 * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
98 * @param[in] buffer Value data buffer.
99 * @param[in] size Value data size.
100 * @param[in] create_flags Flag mask.
101 *
102 * @returns MBED_SUCCESS on success or an error code on failure
103 */
104 virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags) = 0;
105
106 /**
107 * @brief Get one KVStore item, given key.
108 *
109 * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
110 * @param[in] buffer Value data buffer.
111 * @param[in] buffer_size Value data buffer size.
112 * @param[out] actual_size Actual read size (NULL to pass nothing).
113 * @param[in] offset Offset to read from in data.
114 *
115 * @returns MBED_SUCCESS on success or an error code on failure
116 */
117 virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0) = 0;
118
119 /**
120 * @brief Get information of a given key.
121 *
122 * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
123 * @param[out] info Returned information structure (NULL to pass nothing).
124 *
125 * @returns MBED_SUCCESS on success or an error code on failure
126 */
127 virtual int get_info(const char *key, info_t *info = NULL) = 0;
128
129 /**
130 * @brief Remove a KVStore item, given key.
131 *
132 * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
133 *
134 * @returns MBED_SUCCESS on success or an error code on failure
135 */
136 virtual int remove(const char *key) = 0;
137
138
139 /**
140 * @brief Start an incremental KVStore set sequence.
141 *
142 * @param[out] handle Returned incremental set handle.
143 * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
144 * @param[in] final_data_size Final value data size.
145 * @param[in] create_flags Flag mask.
146 *
147 * @returns MBED_SUCCESS on success or an error code on failure
148 */
149 virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags) = 0;
150
151 /**
152 * @brief Add data to incremental KVStore set sequence.
153 *
154 * @param[in] handle Incremental set handle.
155 * @param[in] value_data Value data to add.
156 * @param[in] data_size Value data size.
157 *
158 * @returns MBED_SUCCESS on success or an error code on failure
159 */
160 virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size) = 0;
161
162 /**
163 * @brief Finalize an incremental KVStore set sequence.
164 *
165 * @param[in] handle Incremental set handle.
166 *
167 * @returns MBED_SUCCESS on success or an error code on failure
168 */
169 virtual int set_finalize(set_handle_t handle) = 0;
170
171 /**
172 * @brief Start an iteration over KVStore keys.
173 *
174 * @param[out] it Returned iterator handle.
175 * @param[in] prefix Key prefix (null for all keys).
176 *
177 * @returns MBED_SUCCESS on success or an error code on failure
178 */
179 virtual int iterator_open(iterator_t *it, const char *prefix = NULL) = 0;
180
181 /**
182 * @brief Get next key in iteration.
183 *
184 * @param[in] it Iterator handle.
185 * @param[in] key Buffer for returned key.
186 * @param[in] key_size Key buffer size.
187 *
188 * @returns MBED_SUCCESS on success or an error code on failure
189 */
190 virtual int iterator_next(iterator_t it, char *key, size_t key_size) = 0;
191
192 /**
193 * @brief Close iteration.
194 *
195 * @param[in] it Iterator handle.
196 *
197 * @returns MBED_SUCCESS on success or an error code on failure
198 */
199 virtual int iterator_close(iterator_t it) = 0;
200
201 /** Convenience function for checking key validity.
202 * Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
203 *
204 * @param[in] key Key buffer.
205 *
206 * @returns MBED_SUCCESS on success or an error code on failure
207 */
208 bool is_valid_key(const char *key) const
209 {
210 if (!key || !strlen(key) || (strlen(key) > MAX_KEY_SIZE)) {
211 return false;
212 }
213
214 if (strpbrk(key, " */?:;\"|<>\\")) {
215 return false;
216 }
217 return true;
218 }
219
220};
221/** @}*/
222/** @}*/
223
224} // namespace mbed
225
226#endif
KVStore class.
Definition: KVStore.h:38
struct mbed::KVStore::info info_t
Holds key information.
virtual int remove(const char *key)=0
Remove a KVStore item, given key.
virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags)=0
Set one KVStore item, given key and value.
bool is_valid_key(const char *key) const
Convenience function for checking key validity.
Definition: KVStore.h:208
virtual int set_finalize(set_handle_t handle)=0
Finalize an incremental KVStore set sequence.
virtual int deinit()=0
Deinitialize KVStore.
virtual int get_info(const char *key, info_t *info=NULL)=0
Get information of a given key.
virtual int iterator_next(iterator_t it, char *key, size_t key_size)=0
Get next key in iteration.
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags)=0
Start an incremental KVStore set sequence.
virtual int iterator_open(iterator_t *it, const char *prefix=NULL)=0
Start an iteration over KVStore keys.
virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size=NULL, size_t offset=0)=0
Get one KVStore item, given key.
virtual int reset()=0
Reset KVStore contents (clear all keys)
virtual int init()=0
Initialize KVStore.
virtual int iterator_close(iterator_t it)=0
Close iteration.
virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size)=0
Add data to incremental KVStore set sequence.
Holds key information.
Definition: KVStore.h:56
size_t size
The key size.
Definition: KVStore.h:60