Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
FileSystemStore.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2018 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 #ifndef MBED_FILE_SYSTEM_STORE_H
19 #define MBED_FILE_SYSTEM_STORE_H
20 
21 #include "features/storage/kvstore/include/KVStore.h"
22 #include "features/storage/filesystem/FileSystem.h"
23 
24 namespace mbed {
25 
26 /** FileSystemStore for Secure Store.
27  * This class implements the KVStore interface to
28  * create a key value store over FileSystem.
29  *
30  * @code
31  * ...
32  * @endcode
33  */
34 class FileSystemStore : public KVStore {
35 
36 public:
37  /** Create FileSystemStore - A Key Value API on top of FS
38  *
39  * @param fs File system (FAT/LITTLE) on top of which FileSystemStore is adding KV API
40  */
41  FileSystemStore(FileSystem *fs);
42 
43  /** Destroy FileSystemStore instance
44  *
45  */
46  virtual ~FileSystemStore() {}
47 
48  /**
49  * @brief Initialize FileSystemStore, checking validity of
50  * KVStore writing folder and if it doesn't exist, creating it.
51  *
52  * @returns MBED_SUCCESS Success.
53  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
54  */
55  virtual int init();
56 
57  /**
58  * @brief Deinitialize FileSystemStore, release and free resources.
59  *
60  * @returns MBED_SUCCESS Success.
61  */
62  virtual int deinit();
63 
64  /**
65  * @brief Reset FileSystemStore contents (clear all keys)
66  *
67  * @returns MBED_SUCCESS Success.
68  * MBED_ERROR_NOT_READY Not initialized.
69  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
70  */
71  virtual int reset();
72 
73  /**
74  * @brief Set one FileSystemStore item, given key and value.
75  *
76  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
77  * @param[in] buffer Value data buffer.
78  * @param[in] size Value data size.
79  * @param[in] create_flags Flag mask.
80  *
81  * @returns MBED_SUCCESS Success.
82  * MBED_ERROR_NOT_READY Not initialized.
83  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
84  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
85  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
86  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
87  */
88  virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags);
89 
90  /**
91  * @brief Get one FileSystemStore item by given key.
92  *
93  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
94  * @param[in] buffer Value data buffer.
95  * @param[in] buffer_size Value data buffer size.
96  * @param[out] actual_size Actual read size.
97  * @param[in] offset Offset to read from in data.
98  *
99  * @returns MBED_SUCCESS Success.
100  * MBED_ERROR_NOT_READY Not initialized.
101  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
102  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
103  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
104  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted.
105  * MBED_ERROR_ITEM_NOT_FOUND No such key.
106  */
107  virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0);
108 
109  /**
110  * @brief Get information of a given key. The returned info contains size and flags
111  *
112  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
113  * @param[out] info Returned information structure.
114  *
115  * @returns MBED_SUCCESS Success.
116  * MBED_ERROR_NOT_READY Not initialized.
117  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
118  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
119  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
120  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted.
121  * MBED_ERROR_ITEM_NOT_FOUND No such key.
122  */
123  virtual int get_info(const char *key, info_t *info);
124 
125  /**
126  * @brief Remove a FileSystemStore item by given key.
127  *
128  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
129  *
130  * @returns MBED_SUCCESS Success.
131  * MBED_ERROR_NOT_READY Not initialized.
132  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
133  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
134  * MBED_ERROR_ITEM_NOT_FOUND No such key.
135  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
136  */
137  virtual int remove(const char *key);
138 
139  /**
140  * @brief Start an incremental FileSystemStore set sequence. This operation is blocking other operations.
141  * Any get/set/remove/iterator operation will be blocked until set_finalize is called.
142  *
143  * @param[out] handle Returned incremental set handle.
144  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
145  * @param[in] final_data_size Final value data size.
146  * @param[in] create_flags Flag mask.
147  *
148  * @returns MBED_SUCCESS Success.
149  * MBED_ERROR_NOT_READY Not initialized.
150  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
151  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
152  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
153  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
154  */
155  virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
156 
157  /**
158  * @brief Add data to incremental FileSystemStore set sequence. This operation is blocking other operations.
159  * Any get/set/remove operation will be blocked until set_finalize is called.
160  *
161  * @param[in] handle Incremental set handle.
162  * @param[in] value_data Value data to add.
163  * @param[in] data_size Value data size.
164  *
165  * @returns MBED_SUCCESS Success.
166  * MBED_ERROR_NOT_READY Not initialized.
167  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
168  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
169  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
170  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
171  */
172  virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size);
173 
174  /**
175  * @brief Finalize an incremental FileSystemStore set sequence.
176  *
177  * @param[in] handle Incremental set handle.
178  *
179  * @returns MBED_SUCCESS Success.
180  * MBED_ERROR_NOT_READY Not initialized.
181  * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
182  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
183  */
184  virtual int set_finalize(set_handle_t handle);
185 
186  /**
187  * @brief Start an iteration over FileSystemStore keys.
188  * There are no issues with any other operations while iterator is open.
189  *
190  * @param[out] it Returned iterator handle.
191  * @param[in] prefix Key prefix (null for all keys).
192  *
193  * @returns MBED_SUCCESS Success.
194  * MBED_ERROR_NOT_READY Not initialized.
195  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
196  */
197  virtual int iterator_open(iterator_t *it, const char *prefix = NULL);
198 
199  /**
200  * @brief Get next key in iteration.
201  * There are no issues with any other operations while iterator is open.
202  *
203  * @param[in] it Iterator handle.
204  * @param[in] key Buffer for returned key.
205  * @param[in] key_size Key buffer size.
206  *
207  * @returns MBED_SUCCESS Success.
208  * MBED_ERROR_NOT_READY Not initialized.
209  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
210  * MBED_ERROR_ITEM_NOT_FOUND No more keys found.
211  */
212  virtual int iterator_next(iterator_t it, char *key, size_t key_size);
213 
214  /**
215  * @brief Close iteration.
216  *
217  * @param[in] it Iterator handle.
218  *
219  * @returns MBED_SUCCESS Success.
220  * MBED_ERROR_NOT_READY Not initialized.
221  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
222  */
223  virtual int iterator_close(iterator_t it);
224 
225 #if !defined(DOXYGEN_ONLY)
226 private:
227 
228  // Key metadata
229  typedef struct {
230  uint32_t magic;
231  uint16_t metadata_size;
232  uint16_t revision;
233  uint32_t user_flags;
234  } key_metadata_t;
235 
236  /**
237  * @brief Build Full name class member from Key, as a combination of FSST folder and key name
238  *
239  * @param[in] key_src key file name
240  *
241  * @returns 0 on success or a negative error code on failure
242  */
243  int _build_full_path_key(const char *key_src);
244 
245  /**
246  * @brief Verify Key file metadata validity and open it if valid
247  *
248  * @param[in] key In validated key file name.
249  * @param[in] key_metadata Returned key file metadata.
250  * @param[in] kv_file Opened KV file handle (unless file doesn't exist)
251  *
252  * @returns 0 on success or a negative error code on failure
253  */
254  int _verify_key_file(const char *key, key_metadata_t *key_metadata, File *kv_file);
255 
256  FileSystem *_fs;
257  PlatformMutex _mutex;
258  PlatformMutex _inc_data_add_mutex;
259 
260  bool _is_initialized;
261  char *_cfg_fs_path; /* FileSystemStore path name on FileSystem */
262  size_t _cfg_fs_path_size; /* Size of configured FileSystemStore path name on FileSystem */
263  char *_full_path_key; /* Full name of Key file currently working on */
264  size_t _cur_inc_data_size; /* Amount of data added to Key file so far, during incremental add data */
265  set_handle_t _cur_inc_set_handle; /* handle of currently key file under incremental set process */
266 #endif
267 };
268 
269 
270 } //namespace mbed
271 #endif //MBED_FILE_SYSTEM_STORE_H
mbed::KVStore::info
Holds key information.
Definition: KVStore.h:48
mbed::FileSystemStore::get_info
virtual int get_info(const char *key, info_t *info)
Get information of a given key.
mbed::FileSystemStore::reset
virtual int reset()
Reset FileSystemStore contents (clear all keys)
mbed::FileSystemStore::set_start
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags)
Start an incremental FileSystemStore set sequence.
PlatformMutex
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
mbed::FileSystemStore::deinit
virtual int deinit()
Deinitialize FileSystemStore, release and free resources.
mbed::FileSystemStore
FileSystemStore for Secure Store.
Definition: FileSystemStore.h:34
mbed::FileSystemStore::~FileSystemStore
virtual ~FileSystemStore()
Destroy FileSystemStore instance.
Definition: FileSystemStore.h:46
mbed::KVStore
KVStore class.
Definition: KVStore.h:30
mbed::FileSystemStore::init
virtual int init()
Initialize FileSystemStore, checking validity of KVStore writing folder and if it doesn&#39;t exist...
mbed::File
File class.
Definition: File.h:30
mbed::FileSystem
A file system object.
Definition: FileSystem.h:49
mbed::FileSystemStore::iterator_next
virtual int iterator_next(iterator_t it, char *key, size_t key_size)
Get next key in iteration.
mbed::FileSystemStore::iterator_close
virtual int iterator_close(iterator_t it)
Close iteration.
mbed::FileSystemStore::set_finalize
virtual int set_finalize(set_handle_t handle)
Finalize an incremental FileSystemStore set sequence.
mbed::FileSystemStore::iterator_open
virtual int iterator_open(iterator_t *it, const char *prefix=NULL)
Start an iteration over FileSystemStore keys.
mbed::FileSystemStore::FileSystemStore
FileSystemStore(FileSystem *fs)
Create FileSystemStore - A Key Value API on top of FS.
mbed::FileSystemStore::set_add_data
virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size)
Add data to incremental FileSystemStore 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.