/*
* Copyright (c) 2018 ARM Limited. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
* Licensed under the Apache License, Version 2.0 (the License); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MBED_KVSTORE_H
#define MBED_KVSTORE_H
#include <stdint.h>
#include <stdio.h>
#include <string.h>
namespace mbed {
/**
* \addtogroup storage
* @{
* \defgroup kvstore KVStore
* Classes for key-value storage.
* @{
*/
/** KVStore class
*
* Interface class for all Key Value Storage providers.
*/
class KVStore {
public:
enum create_flags {
WRITE_ONCE_FLAG = (1 << 0),
REQUIRE_CONFIDENTIALITY_FLAG = (1 << 1),
RESERVED_FLAG = (1 << 2),
REQUIRE_REPLAY_PROTECTION_FLAG = (1 << 3),
};
static const uint32_t MAX_KEY_SIZE = 128;
typedef struct _opaque_set_handle *set_handle_t;
typedef struct _opaque_key_iterator *iterator_t;
/**
* Holds key information
*/
typedef struct info {
/**
* The key size
*/
size_t size;
/*
* The Key flags, possible flags combination:
* WRITE_ONCE_FLAG,
* REQUIRE_CONFIDENTIALITY_FLAG,
* REQUIRE_REPLAY_PROTECTION_FLAG
*/
uint32_t flags;
} info_t;
virtual ~KVStore() {};
/**
* @brief Initialize KVStore
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int init() = 0;
/**
* @brief Deinitialize KVStore
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int deinit() = 0;
/**
* @brief Reset KVStore contents (clear all keys)
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int reset() = 0;
/**
* @brief Set one KVStore item, given key and value.
*
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
* @param[in] buffer Value data buffer.
* @param[in] size Value data size.
* @param[in] create_flags Flag mask.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags) = 0;
/**
* @brief Get one KVStore item, given key.
*
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
* @param[in] buffer Value data buffer.
* @param[in] buffer_size Value data buffer size.
* @param[out] actual_size Actual read size (NULL to pass nothing).
* @param[in] offset Offset to read from in data.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0) = 0;
/**
* @brief Get information of a given key.
*
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
* @param[out] info Returned information structure (NULL to pass nothing).
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int get_info(const char *key, info_t *info = NULL) = 0;
/**
* @brief Remove a KVStore item, given key.
*
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int remove(const char *key) = 0;
/**
* @brief Start an incremental KVStore set sequence.
*
* @param[out] handle Returned incremental set handle.
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
* @param[in] final_data_size Final value data size.
* @param[in] create_flags Flag mask.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags) = 0;
/**
* @brief Add data to incremental KVStore set sequence.
*
* @param[in] handle Incremental set handle.
* @param[in] value_data Value data to add.
* @param[in] data_size Value data size.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size) = 0;
/**
* @brief Finalize an incremental KVStore set sequence.
*
* @param[in] handle Incremental set handle.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int set_finalize(set_handle_t handle) = 0;
/**
* @brief Start an iteration over KVStore keys.
*
* @param[out] it Returned iterator handle.
* @param[in] prefix Key prefix (null for all keys).
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int iterator_open(iterator_t *it, const char *prefix = NULL) = 0;
/**
* @brief Get next key in iteration.
*
* @param[in] it Iterator handle.
* @param[in] key Buffer for returned key.
* @param[in] key_size Key buffer size.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int iterator_next(iterator_t it, char *key, size_t key_size) = 0;
/**
* @brief Close iteration.
*
* @param[in] it Iterator handle.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
virtual int iterator_close(iterator_t it) = 0;
/** Convenience function for checking key validity.
* Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
*
* @param[in] key Key buffer.
*
* @returns MBED_SUCCESS on success or an error code on failure
*/
bool is_valid_key(const char *key) const
{
if (!key || !strlen(key) || (strlen(key) > MAX_KEY_SIZE)) {
return false;
}
if (strpbrk(key, " */?:;\"|<>\\")) {
return false;
}
return true;
}
};
/** @}*/
/** @}*/
} // namespace mbed
#endif
