Mistake on this page?
Report an issue in GitHub or email us
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 
24 namespace mbed {
25 
26 /** KVStore class
27  *
28  * Interface class for Key Value Storage
29  */
30 class KVStore {
31 public:
32  enum create_flags {
33  WRITE_ONCE_FLAG = (1 << 0),
34  REQUIRE_CONFIDENTIALITY_FLAG = (1 << 1),
35  RESERVED_FLAG = (1 << 2),
36  REQUIRE_REPLAY_PROTECTION_FLAG = (1 << 3),
37  };
38 
39  static const uint32_t MAX_KEY_SIZE = 128;
40 
41  typedef struct _opaque_set_handle *set_handle_t;
42 
43  typedef struct _opaque_key_iterator *iterator_t;
44 
45  /**
46  * Holds key information
47  */
48  typedef struct info {
49  /**
50  * The key size
51  */
52  size_t size;
53  /*
54  * The Key flags, possible flags combination:
55  * WRITE_ONCE_FLAG,
56  * REQUIRE_CONFIDENTIALITY_FLAG,
57  * REQUIRE_REPLAY_PROTECTION_FLAG
58  */
59  uint32_t flags;
60  } info_t;
61 
62  virtual ~KVStore() {};
63 
64  /**
65  * @brief Initialize KVStore
66  *
67  * @returns MBED_SUCCESS on success or an error code on failure
68  */
69  virtual int init() = 0;
70 
71  /**
72  * @brief Deinitialize KVStore
73  *
74  * @returns MBED_SUCCESS on success or an error code on failure
75  */
76  virtual int deinit() = 0;
77 
78 
79  /**
80  * @brief Reset KVStore contents (clear all keys)
81  *
82  * @returns MBED_SUCCESS on success or an error code on failure
83  */
84  virtual int reset() = 0;
85 
86  /**
87  * @brief Set one KVStore item, given key and value.
88  *
89  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
90  * @param[in] buffer Value data buffer.
91  * @param[in] size Value data size.
92  * @param[in] create_flags Flag mask.
93  *
94  * @returns MBED_SUCCESS on success or an error code on failure
95  */
96  virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags) = 0;
97 
98  /**
99  * @brief Get one KVStore item, given key.
100  *
101  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
102  * @param[in] buffer Value data buffer.
103  * @param[in] buffer_size Value data buffer size.
104  * @param[out] actual_size Actual read size (NULL to pass nothing).
105  * @param[in] offset Offset to read from in data.
106  *
107  * @returns MBED_SUCCESS on success or an error code on failure
108  */
109  virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0) = 0;
110 
111  /**
112  * @brief Get information of a given key.
113  *
114  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
115  * @param[out] info Returned information structure (NULL to pass nothing).
116  *
117  * @returns MBED_SUCCESS on success or an error code on failure
118  */
119  virtual int get_info(const char *key, info_t *info = NULL) = 0;
120 
121  /**
122  * @brief Remove a KVStore item, given key.
123  *
124  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
125  *
126  * @returns MBED_SUCCESS on success or an error code on failure
127  */
128  virtual int remove(const char *key) = 0;
129 
130 
131  /**
132  * @brief Start an incremental KVStore set sequence.
133  *
134  * @param[out] handle Returned incremental set handle.
135  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
136  * @param[in] final_data_size Final value data size.
137  * @param[in] create_flags Flag mask.
138  *
139  * @returns MBED_SUCCESS on success or an error code on failure
140  */
141  virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags) = 0;
142 
143  /**
144  * @brief Add data to incremental KVStore set sequence.
145  *
146  * @param[in] handle Incremental set handle.
147  * @param[in] value_data Value data to add.
148  * @param[in] data_size Value data size.
149  *
150  * @returns MBED_SUCCESS on success or an error code on failure
151  */
152  virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size) = 0;
153 
154  /**
155  * @brief Finalize an incremental KVStore set sequence.
156  *
157  * @param[in] handle Incremental set handle.
158  *
159  * @returns MBED_SUCCESS on success or an error code on failure
160  */
161  virtual int set_finalize(set_handle_t handle) = 0;
162 
163  /**
164  * @brief Start an iteration over KVStore keys.
165  *
166  * @param[out] it Returned iterator handle.
167  * @param[in] prefix Key prefix (null for all keys).
168  *
169  * @returns MBED_SUCCESS on success or an error code on failure
170  */
171  virtual int iterator_open(iterator_t *it, const char *prefix = NULL) = 0;
172 
173  /**
174  * @brief Get next key in iteration.
175  *
176  * @param[in] it Iterator handle.
177  * @param[in] key Buffer for returned key.
178  * @param[in] key_size Key buffer size.
179  *
180  * @returns MBED_SUCCESS on success or an error code on failure
181  */
182  virtual int iterator_next(iterator_t it, char *key, size_t key_size) = 0;
183 
184  /**
185  * @brief Close iteration.
186  *
187  * @param[in] it Iterator handle.
188  *
189  * @returns MBED_SUCCESS on success or an error code on failure
190  */
191  virtual int iterator_close(iterator_t it) = 0;
192 
193  /** Convenience function for checking key validity.
194  * Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
195  *
196  * @param[in] key Key buffer.
197  *
198  * @returns MBED_SUCCESS on success or an error code on failure
199  */
200  bool is_valid_key(const char *key) const
201  {
202  if (!key || !strlen(key) || (strlen(key) > MAX_KEY_SIZE)) {
203  return false;
204  }
205 
206  if (strpbrk(key, " */?:;\"|<>\\")) {
207  return false;
208  }
209  return true;
210  }
211 
212 };
213 /** @}*/
214 
215 } // namespace mbed
216 
217 #endif
virtual int deinit()=0
Deinitialize KVStore.
Holds key information.
Definition: KVStore.h:48
bool is_valid_key(const char *key) const
Convenience function for checking key validity.
Definition: KVStore.h:200
virtual int get_info(const char *key, info_t *info=NULL)=0
Get information of a given key.
virtual int init()=0
Initialize KVStore.
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.
virtual int iterator_close(iterator_t it)=0
Close iteration.
KVStore class.
Definition: KVStore.h:30
virtual int iterator_next(iterator_t it, char *key, size_t key_size)=0
Get next key in iteration.
size_t size
The key size.
Definition: KVStore.h:52
struct mbed::KVStore::info info_t
Holds key information.
virtual int reset()=0
Reset KVStore contents (clear all keys)
virtual int iterator_open(iterator_t *it, const char *prefix=NULL)=0
Start an iteration over KVStore keys.
virtual int set_finalize(set_handle_t handle)=0
Finalize an incremental KVStore set sequence.
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.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.