KVStore.h

00001 /*
00002  * Copyright (c) 2018 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_KVSTORE_H
00018 #define MBED_KVSTORE_H
00019 
00020 #include <stdint.h>
00021 #include <stdio.h>
00022 #include <string.h>
00023 
00024 namespace mbed {
00025 
00026 /** KVStore class
00027  *
00028  *  Interface class for Key Value Storage
00029  */
00030 class KVStore {
00031 public:
00032     enum create_flags {
00033         WRITE_ONCE_FLAG                     = (1 << 0),
00034         REQUIRE_CONFIDENTIALITY_FLAG        = (1 << 1),
00035         RESERVED_FLAG                       = (1 << 2),
00036         REQUIRE_REPLAY_PROTECTION_FLAG      = (1 << 3),
00037     };
00038 
00039     static const uint32_t MAX_KEY_SIZE = 128;
00040 
00041     typedef struct _opaque_set_handle *set_handle_t;
00042 
00043     typedef struct _opaque_key_iterator *iterator_t;
00044 
00045     /**
00046      * Holds key information
00047      */
00048     typedef struct info {
00049         /**
00050          * The key size
00051          */
00052         size_t size;
00053         /*
00054          * The Key flags, possible flags combination:
00055          * WRITE_ONCE_FLAG,
00056          * REQUIRE_CONFIDENTIALITY_FLAG,
00057          * REQUIRE_REPLAY_PROTECTION_FLAG
00058          */
00059         uint32_t flags;
00060     } info_t;
00061 
00062     virtual ~KVStore() {};
00063 
00064     /**
00065      * @brief Initialize KVStore
00066      *
00067      * @returns MBED_SUCCESS on success or an error code on failure
00068      */
00069     virtual int init() = 0;
00070 
00071     /**
00072      * @brief Deinitialize KVStore
00073      *
00074      * @returns MBED_SUCCESS on success or an error code on failure
00075      */
00076     virtual int deinit() = 0;
00077 
00078 
00079     /**
00080      * @brief Reset KVStore contents (clear all keys)
00081      *
00082      * @returns MBED_SUCCESS on success or an error code on failure
00083      */
00084     virtual int reset() = 0;
00085 
00086     /**
00087      * @brief Set one KVStore item, given key and value.
00088      *
00089      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00090      * @param[in]  buffer               Value data buffer.
00091      * @param[in]  size                 Value data size.
00092      * @param[in]  create_flags         Flag mask.
00093      *
00094      * @returns MBED_SUCCESS on success or an error code on failure
00095      */
00096     virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags) = 0;
00097 
00098     /**
00099      * @brief Get one KVStore item, given key.
00100      *
00101      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00102      * @param[in]  buffer               Value data buffer.
00103      * @param[in]  buffer_size          Value data buffer size.
00104      * @param[out] actual_size          Actual read size (NULL to pass nothing).
00105      * @param[in]  offset               Offset to read from in data.
00106      *
00107      * @returns MBED_SUCCESS on success or an error code on failure
00108      */
00109     virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0) = 0;
00110 
00111     /**
00112      * @brief Get information of a given key.
00113      *
00114      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00115      * @param[out] info                 Returned information structure (NULL to pass nothing).
00116      *
00117      * @returns MBED_SUCCESS on success or an error code on failure
00118      */
00119     virtual int get_info(const char *key, info_t *info = NULL) = 0;
00120 
00121     /**
00122      * @brief Remove a KVStore item, given key.
00123      *
00124      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00125      *
00126      * @returns MBED_SUCCESS on success or an error code on failure
00127      */
00128     virtual int remove(const char *key) = 0;
00129 
00130 
00131     /**
00132      * @brief Start an incremental KVStore set sequence.
00133      *
00134      * @param[out] handle               Returned incremental set handle.
00135      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00136      * @param[in]  final_data_size      Final value data size.
00137      * @param[in]  create_flags         Flag mask.
00138      *
00139      * @returns MBED_SUCCESS on success or an error code on failure
00140      */
00141     virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags) = 0;
00142 
00143     /**
00144      * @brief Add data to incremental KVStore set sequence.
00145      *
00146      * @param[in]  handle               Incremental set handle.
00147      * @param[in]  value_data           Value data to add.
00148      * @param[in]  data_size            Value data size.
00149      *
00150      * @returns MBED_SUCCESS on success or an error code on failure
00151      */
00152     virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size) = 0;
00153 
00154     /**
00155      * @brief Finalize an incremental KVStore set sequence.
00156      *
00157      * @param[in]  handle               Incremental set handle.
00158      *
00159      * @returns MBED_SUCCESS on success or an error code on failure
00160      */
00161     virtual int set_finalize(set_handle_t handle) = 0;
00162 
00163     /**
00164      * @brief Start an iteration over KVStore keys.
00165      *
00166      * @param[out] it                   Returned iterator handle.
00167      * @param[in]  prefix               Key prefix (null for all keys).
00168      *
00169      * @returns MBED_SUCCESS on success or an error code on failure
00170      */
00171     virtual int iterator_open(iterator_t *it, const char *prefix = NULL) = 0;
00172 
00173     /**
00174      * @brief Get next key in iteration.
00175      *
00176      * @param[in]  it                   Iterator handle.
00177      * @param[in]  key                  Buffer for returned key.
00178      * @param[in]  key_size             Key buffer size.
00179      *
00180      * @returns MBED_SUCCESS on success or an error code on failure
00181      */
00182     virtual int iterator_next(iterator_t it, char *key, size_t key_size) = 0;
00183 
00184     /**
00185      * @brief Close iteration.
00186      *
00187      * @param[in]  it                   Iterator handle.
00188      *
00189      * @returns MBED_SUCCESS on success or an error code on failure
00190      */
00191     virtual int iterator_close(iterator_t it) = 0;
00192 
00193     /** Convenience function for checking key validity.
00194      *  Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00195      *
00196      * @param[in]  key                  Key buffer.
00197      *
00198      * @returns MBED_SUCCESS on success or an error code on failure
00199      */
00200     bool is_valid_key(const char *key) const
00201     {
00202         if (!key || !strlen(key) || (strlen(key) > MAX_KEY_SIZE)) {
00203             return false;
00204         }
00205 
00206         if (strpbrk(key, " */?:;\"|<>\\")) {
00207             return false;
00208         }
00209         return true;
00210     }
00211 
00212 };
00213 /** @}*/
00214 
00215 } // namespace mbed
00216 
00217 #endif