kvstore_global_api.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 #ifndef _KVSTORE_STATIC_API
00017 #define _KVSTORE_STATIC_API
00018 
00019 #include "stddef.h"
00020 #include "stdint.h"
00021 
00022 #ifdef __cplusplus
00023 extern "C" {
00024 #endif
00025 
00026 typedef struct _opaque_kv_key_iterator *kv_iterator_t;
00027 
00028 #define KV_WRITE_ONCE_FLAG                      (1 << 0)
00029 #define KV_REQUIRE_CONFIDENTIALITY_FLAG         (1 << 1)
00030 #define KV_RESERVED_FLAG                        (1 << 2)
00031 #define KV_REQUIRE_REPLAY_PROTECTION_FLAG       (1 << 3)
00032 
00033 #define KV_MAX_KEY_LENGTH 128
00034 
00035 /**
00036  * The key size
00037  */
00038 typedef struct info {
00039     /**
00040      * The key size
00041      */
00042     size_t size;
00043     /*
00044      * The Key flags, possible flags combination:
00045      * WRITE_ONCE_FLAG,
00046      * REQUIRE_CONFIDENTIALITY_FLAG,
00047      * REQUIRE_REPLAY_PROTECTION_FLAG
00048      */
00049     uint32_t flags;
00050 } kv_info_t;
00051 
00052 /**
00053  * @brief Set one KVStore item, given key and value.
00054  *
00055  * @param[in]  full_name_key        /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00056  * @param[in]  buffer               Value data buffer.
00057  * @param[in]  size                 Value data size.
00058  * @param[in]  create_flags         Flag mask.
00059  *
00060  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00061  */
00062 int kv_set(const char *full_name_key, const void *buffer, size_t size, uint32_t create_flags);
00063 
00064 /**
00065  * @brief Get one KVStore item by given key.
00066  *
00067  * @param[in]  full_name_key        /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00068  * @param[in]  buffer               Value data buffer.
00069  * @param[in]  buffer_size          Value data buffer size.
00070  * @param[out] actual_size          Actual read size.
00071  *
00072  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00073  */
00074 int kv_get(const char *full_name_key, void *buffer, size_t buffer_size, size_t *actual_size);
00075 
00076 /**
00077  * @brief Get information of a given key.The returned info contains size and flags
00078  *
00079  * @param[in]  full_name_key        /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00080  * @param[out] info                 Returned information structure.
00081  *
00082  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00083  */
00084 int kv_get_info(const char *full_name_key, kv_info_t *info);
00085 
00086 /**
00087  * @brief Remove a KVStore item by given key.
00088  *
00089  * @param[in]  full_name_key        /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00090  *
00091  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00092  */
00093 int kv_remove(const char *full_name_key);
00094 
00095 /**
00096  * @brief Start an iteration over KVStore keys to find all the entries
00097  *        that fit the full_prefix. There are no issues with any other operations while
00098  *        iterator is open.
00099  *
00100  * @param[out] it                   Allocating iterator handle.
00101  *                                  Do not forget to call kv_iterator_close
00102  *                                  to deallocate the memory.
00103  * @param[in]  full_prefix          full_prefix Partition/Key prefix. If
00104  *                                  empty key or NULL pointer, all keys
00105  *                                  will match.
00106  *
00107  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00108  */
00109 int kv_iterator_open(kv_iterator_t *it, const char *full_prefix);
00110 
00111 /**
00112  * @brief Get next key in iteration that matches the prefix. There are no issues with any
00113  *        other operations while iterator is open.
00114  *
00115  * @param[in]  it                   Iterator handle.
00116  * @param[in]  key                  Buffer for returned key.
00117  * @param[in]  key_size             Key buffer size.
00118  *
00119  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00120  */
00121 int kv_iterator_next(kv_iterator_t it, char *key, size_t key_size);
00122 
00123 /**
00124  * @brief Close iteration and deallocate the iterator handle.
00125  *
00126  * @param[in]  it                   Iterator handle.
00127  *
00128  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00129  */
00130 int kv_iterator_close(kv_iterator_t it);
00131 
00132 /**
00133  * @brief Remove all keys and related data from a specified partition.
00134  *
00135  * @param[in]  kvstore_path        /Partition/
00136  *
00137  * @returns MBED_SUCCESS on success or an error code from underlying KVStore instances
00138  */
00139 int kv_reset(const char *kvstore_path);
00140 
00141 #ifdef __cplusplus
00142 } // closing brace for extern "C"
00143 #endif
00144 #endif