FileSystemStore.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * SPDX-License-Identifier: Apache-2.0
00005  *
00006  * Licensed under the Apache License, Version 2.0 (the "License");
00007  * you may not use this file except in compliance with the License.
00008  * You may obtain a copy of the License at
00009  *
00010  *     http://www.apache.org/licenses/LICENSE-2.0
00011  *
00012  * Unless required by applicable law or agreed to in writing, software
00013  * distributed under the License is distributed on an "AS IS" BASIS,
00014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015  * See the License for the specific language governing permissions and
00016  * limitations under the License.
00017  */
00018 #ifndef MBED_FILE_SYSTEM_STORE_H
00019 #define MBED_FILE_SYSTEM_STORE_H
00020 
00021 #include "features/storage/kvstore/include/KVStore.h"
00022 #include "features/storage/filesystem/FileSystem.h"
00023 
00024 namespace mbed {
00025 
00026 /** FileSystemStore for Secure Store.
00027  *  This class implements the KVStore interface to
00028  *  create a key value store over FileSystem.
00029  *
00030  *  @code
00031  *  ...
00032  *  @endcode
00033  */
00034 class FileSystemStore : public KVStore {
00035 
00036 public:
00037     /** Create FileSystemStore - A Key Value API on top of FS
00038      *
00039      *  @param fs File system (FAT/LITTLE) on top of which FileSystemStore is adding KV API
00040      */
00041     FileSystemStore(FileSystem *fs);
00042 
00043     /** Destroy FileSystemStore instance
00044      *
00045      */
00046     virtual ~FileSystemStore() {}
00047 
00048     /**
00049       * @brief Initialize FileSystemStore, checking validity of
00050       *        KVStore writing folder and if it doesn't exist, creating it.
00051       *
00052       * @returns MBED_SUCCESS                        Success.
00053       *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00054       */
00055     virtual int init();
00056 
00057     /**
00058       * @brief Deinitialize FileSystemStore, release and free resources.
00059       *
00060       * @returns MBED_SUCCESS                        Success.
00061       */
00062     virtual int deinit();
00063 
00064     /**
00065      * @brief Reset FileSystemStore contents (clear all keys)
00066      *
00067      * @returns MBED_SUCCESS                        Success.
00068      *          MBED_ERROR_NOT_READY                Not initialized.
00069      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00070      */
00071     virtual int reset();
00072 
00073     /**
00074      * @brief Set one FileSystemStore item, given key and value.
00075      *
00076      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00077      * @param[in]  buffer               Value data buffer.
00078      * @param[in]  size                 Value data size.
00079      * @param[in]  create_flags         Flag mask.
00080      *
00081      * @returns MBED_SUCCESS                        Success.
00082      *          MBED_ERROR_NOT_READY                Not initialized.
00083      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00084      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00085      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00086      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00087      */
00088     virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags);
00089 
00090     /**
00091       * @brief Get one FileSystemStore item by given key.
00092       *
00093       * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00094       * @param[in]  buffer               Value data buffer.
00095       * @param[in]  buffer_size          Value data buffer size.
00096       * @param[out] actual_size          Actual read size.
00097       * @param[in]  offset               Offset to read from in data.
00098       *
00099       * @returns MBED_SUCCESS                        Success.
00100       *          MBED_ERROR_NOT_READY                Not initialized.
00101       *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00102       *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00103       *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00104       *          MBED_ERROR_INVALID_DATA_DETECTED    Data is corrupted.
00105       *          MBED_ERROR_ITEM_NOT_FOUND           No such key.
00106       */
00107     virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0);
00108 
00109     /**
00110      * @brief Get information of a given key. The returned info contains size and flags
00111      *
00112      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00113      * @param[out] info                 Returned information structure.
00114      *
00115       * @returns MBED_SUCCESS                        Success.
00116       *          MBED_ERROR_NOT_READY                Not initialized.
00117       *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00118       *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00119       *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00120       *          MBED_ERROR_INVALID_DATA_DETECTED    Data is corrupted.
00121       *          MBED_ERROR_ITEM_NOT_FOUND           No such key.
00122      */
00123     virtual int get_info(const char *key, info_t *info);
00124 
00125     /**
00126      * @brief Remove a FileSystemStore item by given key.
00127      *
00128      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00129      *
00130      * @returns MBED_SUCCESS                        Success.
00131      *          MBED_ERROR_NOT_READY                Not initialized.
00132      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00133      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00134      *          MBED_ERROR_ITEM_NOT_FOUND           No such key.
00135      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00136      */
00137     virtual int remove(const char *key);
00138 
00139     /**
00140      * @brief Start an incremental FileSystemStore set sequence. This operation is blocking other operations.
00141      *        Any get/set/remove/iterator operation will be blocked until set_finalize is called.
00142      *
00143      * @param[out] handle               Returned incremental set handle.
00144      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00145      * @param[in]  final_data_size      Final value data size.
00146      * @param[in]  create_flags         Flag mask.
00147      *
00148      * @returns MBED_SUCCESS                        Success.
00149      *          MBED_ERROR_NOT_READY                Not initialized.
00150      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00151      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00152      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00153      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00154      */
00155     virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
00156 
00157     /**
00158      * @brief Add data to incremental FileSystemStore set sequence. This operation is blocking other operations.
00159      *        Any get/set/remove operation will be blocked until set_finalize is called.
00160      *
00161      * @param[in]  handle               Incremental set handle.
00162      * @param[in]  value_data           Value data to add.
00163      * @param[in]  data_size            Value data size.
00164      *
00165      * @returns MBED_SUCCESS                        Success.
00166      *          MBED_ERROR_NOT_READY                Not initialized.
00167      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00168      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00169      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00170      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00171      */
00172     virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size);
00173 
00174     /**
00175      * @brief Finalize an incremental FileSystemStore set sequence.
00176      *
00177      * @param[in]  handle               Incremental set handle.
00178      *
00179      * @returns MBED_SUCCESS                        Success.
00180      *          MBED_ERROR_NOT_READY                Not initialized.
00181      *          MBED_ERROR_FAILED_OPERATION         Underlying file system failed operation.
00182      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00183      */
00184     virtual int set_finalize(set_handle_t handle);
00185 
00186     /**
00187      * @brief Start an iteration over FileSystemStore keys.
00188      *        There are no issues with any other operations while iterator is open.
00189      *
00190      * @param[out] it                   Returned iterator handle.
00191      * @param[in]  prefix               Key prefix (null for all keys).
00192      *
00193      * @returns MBED_SUCCESS                        Success.
00194      *          MBED_ERROR_NOT_READY                Not initialized.
00195      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00196      */
00197     virtual int iterator_open(iterator_t *it, const char *prefix = NULL);
00198 
00199     /**
00200      * @brief Get next key in iteration.
00201      *        There are no issues with any other operations while iterator is open.
00202      *
00203      * @param[in]  it                   Iterator handle.
00204      * @param[in]  key                  Buffer for returned key.
00205      * @param[in]  key_size             Key buffer size.
00206      *
00207      * @returns MBED_SUCCESS                        Success.
00208      *          MBED_ERROR_NOT_READY                Not initialized.
00209      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00210      *          MBED_ERROR_ITEM_NOT_FOUND           No more keys found.
00211      */
00212     virtual int iterator_next(iterator_t it, char *key, size_t key_size);
00213 
00214     /**
00215      * @brief Close iteration.
00216      *
00217      * @param[in]  it                   Iterator handle.
00218      *
00219      * @returns MBED_SUCCESS                        Success.
00220      *          MBED_ERROR_NOT_READY                Not initialized.
00221      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00222      */
00223     virtual int iterator_close(iterator_t it);
00224 
00225 #if !defined(DOXYGEN_ONLY)
00226 private:
00227 
00228     // Key metadata
00229     typedef struct {
00230         uint32_t magic;
00231         uint16_t metadata_size;
00232         uint16_t revision;
00233         uint32_t user_flags;
00234     } key_metadata_t;
00235 
00236     /**
00237      * @brief Build Full name class member from Key, as a combination of FSST folder and key name
00238      *
00239      * @param[in]  key_src              key file name
00240      *
00241      * @returns 0 on success or a negative error code on failure
00242      */
00243     int _build_full_path_key(const char *key_src);
00244 
00245     /**
00246      * @brief Verify Key file metadata validity and open it if valid
00247      *
00248      * @param[in]  key                  In validated key file name.
00249      * @param[in]  key_metadata         Returned key file metadata.
00250      * @param[in]  kv_file              Opened KV file handle (unless file doesn't exist)
00251      *
00252      * @returns 0 on success or a negative error code on failure
00253      */
00254     int _verify_key_file(const char *key, key_metadata_t *key_metadata, File *kv_file);
00255 
00256     FileSystem *_fs;
00257     PlatformMutex _mutex;
00258     PlatformMutex _inc_data_add_mutex;
00259 
00260     bool _is_initialized;
00261     char *_cfg_fs_path; /* FileSystemStore path name on FileSystem */
00262     size_t _cfg_fs_path_size; /* Size of configured FileSystemStore path name on FileSystem */
00263     char *_full_path_key; /* Full name of Key file currently working on */
00264     size_t _cur_inc_data_size; /* Amount of data added to Key file so far, during incremental add data */
00265     set_handle_t _cur_inc_set_handle; /* handle of currently key file under incremental set process */
00266 #endif
00267 };
00268 
00269 
00270 } //namespace mbed
00271 #endif //MBED_FILE_SYSTEM_STORE_H