键值存储接口

[English]

公共头文件： #include "brookesia/hal_interface/interfaces/storage/key_value.hpp"

类名： KeyValueIface

KeyValueIface 定义平台无关的键值存储契约， 供 Service 层使用。 ESP-IDF 适配实现可基于 NVS，PC 或模拟器适配实现则可使用 确定性的内存后端，而无需改变 service helper 的 schema。

API 参考

Header File

• hal/brookesia_hal_interface/include/brookesia/hal_interface/interfaces/storage/key_value.hpp

Classes

class KeyValueIface : public esp_brookesia::hal::Interface

Generic namespace-based key-value storage interface.

Public Types

enum class ValueType

Supported stored value type.

Values:

enumerator Bool

Boolean value.

enumerator Int

32-bit signed integer value.

enumerator String

String value.

enumerator Max

Invalid value type.

using Value = std::variant<bool, int32_t, std::string>

Value stored in a key-value namespace.

using KeyValueMap = std::map<std::string, Value>

Key-value mapping payload for batch operations.

Public Functions

inline KeyValueIface()

Construct a key-value storage interface.

virtual ~KeyValueIface() = default

Virtual destructor for polymorphic storage interfaces.

virtual bool init() = 0

Initialize the key-value storage backend.

返回

true on success, otherwise false.

virtual void deinit() = 0

Deinitialize the key-value storage backend.

virtual bool list(const std::string &nspace, std::vector<EntryInfo> &entries) = 0

List entries under a namespace.

参数

• nspace -- [in] Namespace to list.

• entries -- [out] Listed entries.

返回

true on success, otherwise false.

virtual bool set(const std::string &nspace, const KeyValueMap &key_value_map) = 0

Set key-value pairs under a namespace.

参数

• nspace -- [in] Namespace to write.

• key_value_map -- [in] Values to write.

返回

true on success, otherwise false.

virtual bool get(const std::string &nspace, const std::vector<std::string> &keys, KeyValueMap &key_value_map) = 0

Get key-value pairs under a namespace.

Passing an empty key list returns all entries in the namespace.

参数

• nspace -- [in] Namespace to read.

• keys -- [in] Keys to read. Empty means all keys.

• key_value_map -- [out] Read values.

返回

true on success, otherwise false.

virtual bool erase(const std::string &nspace, const std::vector<std::string> &keys) = 0

Erase keys under a namespace.

Passing an empty key list erases the whole namespace.

参数

• nspace -- [in] Namespace to erase.

• keys -- [in] Keys to erase. Empty means all keys.

返回

true on success, otherwise false.

inline const std::string &get_last_error() const

Get the most recent backend error.

返回

Human-readable error string.

inline const Info &get_info() const

Get key-value backend capability limits.

返回

Key-value backend information.

Public Static Attributes

static constexpr const char *NAME = "StorageKeyValue"

Interface registry name.

struct EntryInfo

Metadata for one stored entry.

Public Members

std::string nspace

Namespace name.

std::string key

Entry key.

ValueType type

Entry value type.

struct Info

Capability limits exposed by the key-value backend.

A value of 0 means the backend does not declare a limit for that field.

Public Members

uint32_t max_namespace_length = 0

Maximum namespace length in characters.

uint32_t max_key_length = 0

Maximum key length in characters.