Storage Helper

[English]

  • 公共头文件： #include "brookesia/service_helper/system/storage.hpp"

概述

本页用于查看 Storage helper 的原始 Doxygen API，包括公共类型、枚举、方法与相关宏定义。

API 参考

Header File

Classes

class Storage : public esp_brookesia::service::helper::Base<Storage>

Helper schema definitions for the Storage service.

Public Types

enum class FunctionId

Storage service function identifiers.

Values:

enumerator KVList
enumerator KVSet
enumerator KVGet
enumerator KVErase
enumerator GetFileSystems
enumerator GetFileSystemCapacity
enumerator MakeKVKey
enumerator MakeKVNamespace
enumerator Max
enum class EventId

Storage service event identifiers.

Values:

enumerator Max
enum class FunctionKVListParam

Parameter keys for FunctionId::KVList.

Values:

enumerator Nspace
enum class FunctionKVSetParam

Parameter keys for FunctionId::KVSet.

Values:

enumerator Nspace
enumerator KeyValuePairs
enum class FunctionKVGetParam

Parameter keys for FunctionId::KVGet.

Values:

enumerator Nspace
enumerator Keys
enum class FunctionKVEraseParam

Parameter keys for FunctionId::KVErase.

Values:

enumerator Nspace
enumerator Keys
using ValueType = hal::storage::KeyValueIface::ValueType

They are used as parameter and return types for functions and events. Users can access or modify these types via serialization and deserialization.

Public Static Functions

static inline constexpr std::string_view get_name()

Service name used by ServiceManager.

返回

std::string_view Stable service name.

static inline std::span<const FunctionSchema> get_function_schemas()

Get function schemas exported by Storage service.

返回

std::span<const FunctionSchema> Static function schema span.

static inline std::span<const EventSchema> get_event_schemas()

Get event schemas exported by Storage service.

返回

std::span<const EventSchema> Empty span because Storage has no events.

template<typename T>
static inline std::expected<void, std::string> save_key_value(const std::string &nspace, const std::string &key, const T &value, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Save key-value pairs to the Storage namespace.

Direct Storage (No Serialization):

  • bool: Stored directly as JSON boolean value (true/false)

  • int32_t: Stored directly as JSON number (int64_t in JSON)

  • Integer types with size <= 32 bits (int8_t, uint8_t, int16_t, uint16_t, char, short, etc.): Converted to int32_t and stored as JSON number for optimal performance

Serialized Storage:

  • Integer types with size > 32 bits (int64_t, uint64_t, long long, etc.): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • Floating point types (float, double): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • String types (std::string, const char*): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • Complex types (std::vector, std::map, custom structs, etc.): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

备注

The storage method depends on the type T:

模板参数

T -- The type of the value to save

参数

  • nspace -- The namespace of the key-value pairs to save

  • key -- The key of the key-value pair to save

  • value -- The value of the key-value pair to save

  • timeout_ms -- The timeout in milliseconds

返回

std::expected<void, std::string> The result of the operation

template<typename T>
static inline bool save_key_value_async(const std::string &nspace, const std::string &key, const T &value, ServiceBase::FunctionResultHandler handler = nullptr)

Save key-value pairs to the Storage namespace asynchronously.

The value conversion rules are identical to save_key_value(). The helper keeps a temporary Storage service binding alive until the asynchronous function result is delivered.

模板参数

T -- The type of the value to save

参数

  • nspace -- The namespace of the key-value pairs to save

  • key -- The key of the key-value pair to save

  • value -- The value of the key-value pair to save

  • handler -- Optional result handler

返回

true if the async call was submitted, false otherwise

template<typename T>
static inline std::expected<T, std::string> get_key_value(const std::string &nspace, const std::string &key, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Get key-value pair from the Storage namespace.

Direct Retrieval (No Deserialization):

  • bool: Retrieved directly from JSON boolean value

  • int32_t: Retrieved directly from JSON number

  • Integer types with size <= 32 bits (int8_t, uint8_t, int16_t, uint16_t, char, short, etc.): Retrieved directly from JSON number and converted to the target integer type

Deserialized Retrieval:

  • Integer types with size > 32 bits (int64_t, uint64_t, long long, etc.): Retrieved directly from JSON string and deserialized to the target integer type

  • Floating point types (float, double): Retrieved directly from JSON string and deserialized to the target floating point type

  • String types (std::string): Retrieved directly from JSON string and deserialized to the target string type

  • Complex types (std::vector, std::map, custom structs, etc.): Retrieved directly from JSON string and deserialized to the target complex type

备注

The retrieval method depends on the type T and matches the storage method used in save_key_value():

模板参数

T -- The type of the value to retrieve

参数

  • nspace -- The namespace of the key-value pair to retrieve

  • key -- The key of the key-value pair to retrieve

  • timeout_ms -- The timeout in milliseconds

返回

std::expected<T, std::string> The retrieved value or error message

static inline std::expected<void, std::string> erase_keys(const std::string &nspace, const std::vector<std::string> &keys = {}, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Erase key-value pairs from the Storage namespace.

参数

  • nspace -- The namespace of the key-value pairs to erase

  • keys -- The keys of the key-value pairs to erase, optional. If not provided or empty, all key-value pairs in the namespace will be erased

  • timeout_ms -- The timeout in milliseconds

返回

std::expected<void, std::string> The result of the operation

Public Static Attributes

static constexpr uint32_t DEFAULT_TIMEOUT_MS = 1000

Default timeout for synchronous Storage helper calls.

struct KvNameResult