Non-Volatile Storage handle. More...

Classes
class	error_category
	Error category for NVS errors. More...

class	flash

Public Types
enum class	errc : esp_err_t { not_initialized = 0x1101 , not_found = 0x1102 , type_mismatch = 0x1103 , read_only = 0x1104 , not_enough_space = 0x1105 , invalid_name = 0x1106 , invalid_handle = 0x1107 , remove_failed = 0x1108 , key_too_long = 0x1109 , invalid_state = 0x110b , invalid_length = 0x110c , no_free_pages = 0x110d , value_too_long = 0x110e , part_not_found = 0x110f , new_version_found = 0x1110 , xts_encr_failed = 0x1111 , xts_decr_failed = 0x1112 , xts_cfg_failed = 0x1113 , xts_cfg_not_found = 0x1114 , encr_not_supported = 0x1115 , keys_not_initialized = 0x1116 , corrupt_key_part = 0x1117 , wrong_encryption = 0x1119 }
	Error codes for NVS operations. More...

Public Member Functions
	nvs (std::string_view namespace_name, bool read_only=false)
	Opens a NVS namespace.

	nvs (const partition &part, std::string_view namespace_name, bool read_only=false)
	Opens a NVS namespace on a specific partition.

	~nvs ()

	nvs (const nvs &)=delete

nvs &	operator= (const nvs &)=delete

	nvs (nvs &&other) noexcept
	Move constructor.

nvs &	operator= (nvs &&other) noexcept
	Move assignment.

bool	is_writeable () const
	Returns true if the handle allows writes.

void	commit ()
	Commits pending changes to flash.

void	erase (std::string_view key)
	Erases a key.

void	erase_all ()
	Erases all keys in the namespace.

void	set_string (std::string_view key, std::string_view value)
	Stores a string.

std::string	get_string (std::string_view key)
	Retrieves a string.

void	set_blob (std::string_view key, const void *data, size_t length)
	Stores binary data.

void	set_blob (std::string_view key, std::span< const uint8_t > data)
	Stores binary data.

std::vector< uint8_t >	get_blob (std::string_view key)
	Retrieves binary data.

template<typename T > requires sized_integral<T>
void	set_value (std::string_view key, T value)
	Stores an integer value.

template<typename T > requires sized_integral<T>
T	get_value (std::string_view key)
	Retrieves an integer value.

result< void >	try_commit ()
	Commits pending changes to flash.

result< void >	try_erase (std::string_view key)
	Erases a key.

result< void >	try_erase_all ()
	Erases all keys in the namespace.

result< void >	try_set_string (std::string_view key, std::string_view value)
	Stores a string.

result< std::string >	try_get_string (std::string_view key)
	Retrieves a string.

result< void >	try_set_blob (std::string_view key, const void *data, size_t length)
	Stores binary data.

result< void >	try_set_blob (std::string_view key, std::span< const uint8_t > data)
	Stores binary data.

result< std::vector< uint8_t > >	try_get_blob (std::string_view key)
	Retrieves binary data.

template<typename T > requires sized_integral<T>
result< void >	try_set_value (std::string_view key, T value)
	Stores an integer value.

template<typename T > requires sized_integral<T>
result< T >	try_get_value (std::string_view key)
	Retrieves an integer value.

Static Public Member Functions
static result< nvs >	make (std::string_view namespace_name, bool read_only=false)
	Opens a NVS namespace.

static result< nvs >	make (const partition &part, std::string_view namespace_name, bool read_only=false)
	Opens a NVS namespace on a specific partition.

Detailed Description

Non-Volatile Storage handle.

Provides persistent key-value storage in flash memory. Supports strings, binary blobs, and integer types from 8 to 64 bits.

This type is non-copyable and move-only. Result-returning methods on a moved-from object return nvs::errc::invalid_handle. Simple accessors return default values.

Changes are not persisted until commit() is called.

Definition at line 58 of file nvs.hpp.

Member Enumeration Documentation

◆ errc

enum class idfxx::nvs::errc : esp_err_t

strong

Error codes for NVS operations.

Enumerator
not_initialized	NVS storage was not initialized. Call nvs::flash::init() first.
not_found	A requested entry couldn’t be found or namespace doesn’t exist yet and mode is NVS_READONLY
type_mismatch	The type of set or get operation doesn't match the type of value stored in NVS
read_only	Storage handle was opened as read only
not_enough_space	There is not enough space in the underlying storage to save the value
invalid_name	Namespace name doesn’t satisfy constraints
invalid_handle	Handle has been closed or is NULL
remove_failed	The value wasn’t updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn’t fail again.
key_too_long	Key name is too long
invalid_state	NVS is in an inconsistent state due to a previous error. Call nvs::flash::init() again and create a new nvs object.
invalid_length	String or blob length is not sufficient to store data
no_free_pages	NVS partition doesn't contain any empty pages. This may happen if NVS partition was truncated. Erase the whole partition and call nvs::flash::init() again.
value_too_long	Value doesn't fit into the entry or string or blob length is longer than supported by the implementation
part_not_found	Partition with specified name is not found in the partition table
new_version_found	NVS partition contains data in new format and cannot be recognized by this version of code
xts_encr_failed	XTS encryption failed while writing NVS entry
xts_decr_failed	XTS decryption failed while reading NVS entry
xts_cfg_failed	XTS configuration setting failed
xts_cfg_not_found	XTS configuration not found
encr_not_supported	NVS encryption is not supported in this version
keys_not_initialized	NVS key partition is uninitialized
corrupt_key_part	NVS key partition is corrupt
wrong_encryption	NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption works differently.

Definition at line 63 of file nvs.hpp.

Constructor & Destructor Documentation

◆ nvs() [1/4]

idfxx::nvs::nvs	(	std::string_view	namespace_name,
		bool	read_only = `false`
	)

explicit

Opens a NVS namespace.

Parameters

namespace_name	Namespace name (max 15 characters).
read_only	If true, opens in read-only mode.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ nvs() [2/4]

idfxx::nvs::nvs	(	const partition &	part,
		std::string_view	namespace_name,
		bool	read_only = `false`
	)

explicit

Opens a NVS namespace on a specific partition.

Parameters

part	The partition to open NVS storage from.
namespace_name	Namespace name (max 15 characters).
read_only	If true, opens in read-only mode.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ ~nvs()

idfxx::nvs::~nvs ( )

◆ nvs() [3/4]

idfxx::nvs::nvs ( const nvs & )

delete

◆ nvs() [4/4]

idfxx::nvs::nvs ( nvs && other )

noexcept

Move constructor.

Transfers handle ownership.

Member Function Documentation

◆ commit()

void idfxx::nvs::commit ( )

inline

Commits pending changes to flash.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 174 of file nvs.hpp.

References try_commit(), and idfxx::unwrap().

◆ erase()

void idfxx::nvs::erase ( std::string_view key )

inline

Erases a key.

Parameters

key	The key to erase.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 182 of file nvs.hpp.

References try_erase(), and idfxx::unwrap().

◆ erase_all()

void idfxx::nvs::erase_all ( )

inline

Erases all keys in the namespace.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 189 of file nvs.hpp.

References try_erase_all(), and idfxx::unwrap().

◆ get_blob()

std::vector< uint8_t > idfxx::nvs::get_blob ( std::string_view key )

inline

Retrieves binary data.

Parameters

key Key name.

Returns: The data.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 235 of file nvs.hpp.

References try_get_blob(), and idfxx::unwrap().

◆ get_string()

std::string idfxx::nvs::get_string ( std::string_view key )

inline

Retrieves a string.

Parameters

key Key name.

Returns: The string value.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 207 of file nvs.hpp.

References try_get_string(), and idfxx::unwrap().

◆ get_value()

template<typename T >
requires sized_integral<T>

T idfxx::nvs::get_value ( std::string_view key )

inline

Retrieves an integer value.

Template Parameters

T	Integer type (8 to 64 bits, signed or unsigned).

Parameters

key Key name.

Returns: The value.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 261 of file nvs.hpp.

References idfxx::unwrap().

◆ is_writeable()

bool idfxx::nvs::is_writeable ( ) const

inline

Returns true if the handle allows writes.

Definition at line 166 of file nvs.hpp.

◆ make() [1/2]

static result< nvs > idfxx::nvs::make	(	const partition &	part,
		std::string_view	namespace_name,
		bool	read_only = `false`
	)

static

Opens a NVS namespace on a specific partition.

Parameters

part	The partition to open NVS storage from.
namespace_name	Namespace name (max 15 characters).
read_only	If true, opens in read-only mode.

Returns: The new nvs handle, or an error.

◆ make() [2/2]

static result< nvs > idfxx::nvs::make	(	std::string_view	namespace_name,
		bool	read_only = `false`
	)

static

Opens a NVS namespace.

Parameters

namespace_name	Namespace name (max 15 characters).
read_only	If true, opens in read-only mode.

Returns: The new nvs handle, or an error.

◆ operator=() [1/2]

nvs & idfxx::nvs::operator= ( const nvs & )

delete

◆ operator=() [2/2]

nvs & idfxx::nvs::operator= ( nvs && other )

noexcept

Move assignment.

Transfers handle ownership.

◆ set_blob() [1/2]

void idfxx::nvs::set_blob	(	std::string_view	key,
		const void *	data,
		size_t	length
	)

inline

Stores binary data.

Parameters

key	Key name.
data	Data pointer.
length	Data size in bytes.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 217 of file nvs.hpp.

References try_set_blob(), and idfxx::unwrap().

◆ set_blob() [2/2]

void idfxx::nvs::set_blob	(	std::string_view	key,
		std::span< const uint8_t >	data
	)

inline

Stores binary data.

Parameters

key	Key name.
data	Data to store.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 226 of file nvs.hpp.

References try_set_blob(), and idfxx::unwrap().

◆ set_string()

void idfxx::nvs::set_string	(	std::string_view	key,
		std::string_view	value
	)

inline

Stores a string.

Parameters

key	Key name.
value	String value.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 198 of file nvs.hpp.

References try_set_string(), and idfxx::unwrap().

◆ set_value()

template<typename T >
requires sized_integral<T>

void idfxx::nvs::set_value	(	std::string_view	key,
		T	value
	)

inline

Stores an integer value.

Template Parameters

T	Integer type (8 to 64 bits, signed or unsigned).

Parameters

key	Key name.
value	Value to store.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on error.

Definition at line 247 of file nvs.hpp.

References try_set_value(), and idfxx::unwrap().

◆ try_commit()

result< void > idfxx::nvs::try_commit ( )

Commits pending changes to flash.

Returns: Success, or an error.

Referenced by commit().

◆ try_erase()

result< void > idfxx::nvs::try_erase ( std::string_view key )

Erases a key.

Parameters

key	The key to erase.

Returns: Success, or an error.

Referenced by erase().

◆ try_erase_all()

result< void > idfxx::nvs::try_erase_all ( )

Erases all keys in the namespace.

Returns: Success, or an error.

Referenced by erase_all().

◆ try_get_blob()

result< std::vector< uint8_t > > idfxx::nvs::try_get_blob ( std::string_view key )

Retrieves binary data.

Parameters

key Key name.

Returns: The data, or an error.

Referenced by get_blob().

◆ try_get_string()

result< std::string > idfxx::nvs::try_get_string ( std::string_view key )

Retrieves a string.

Parameters

key Key name.

Returns: The string value, or an error.

Referenced by get_string().

◆ try_get_value()

template<typename T >
requires sized_integral<T>

result< T > idfxx::nvs::try_get_value ( std::string_view key )

Retrieves an integer value.

Template Parameters

T	Integer type (8 to 64 bits, signed or unsigned).

Parameters

key Key name.

Returns: The value, or an error.

◆ try_set_blob() [1/2]

result< void > idfxx::nvs::try_set_blob	(	std::string_view	key,
		const void *	data,
		size_t	length
	)

Stores binary data.

Parameters

key	Key name.
data	Data pointer.
length	Data size in bytes.

Returns: Success, or an error.

Referenced by set_blob(), and set_blob().

◆ try_set_blob() [2/2]

result< void > idfxx::nvs::try_set_blob	(	std::string_view	key,
		std::span< const uint8_t >	data
	)

Stores binary data.

Parameters

key	Key name.
data	Data to store.

Returns: Success, or an error.

◆ try_set_string()

result< void > idfxx::nvs::try_set_string	(	std::string_view	key,
		std::string_view	value
	)

Stores a string.

Parameters

key	Key name.
value	String value.

Returns: Success, or an error.

Referenced by set_string().

◆ try_set_value()

template<typename T >
requires sized_integral<T>

result< void > idfxx::nvs::try_set_value	(	std::string_view	key,
		T	value
	)

Stores an integer value.

Template Parameters

T	Integer type (8 to 64 bits, signed or unsigned).

Parameters

key	Key name.
value	Value to store.

Returns: Success, or an error.

Referenced by set_value().

The documentation for this class was generated from the following file:

idfxx_nvs/include/idfxx/nvs.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ errc

Constructor & Destructor Documentation

◆ nvs() [1/4]

◆ nvs() [2/4]

◆ ~nvs()

◆ nvs() [3/4]

◆ nvs() [4/4]

Member Function Documentation

◆ commit()

◆ erase()

◆ erase_all()

◆ get_blob()

◆ get_string()

◆ get_value()

◆ is_writeable()

◆ make() [1/2]

◆ make() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_blob() [1/2]

◆ set_blob() [2/2]

◆ set_string()

◆ set_value()

◆ try_commit()

◆ try_erase()

◆ try_erase_all()

◆ try_get_blob()

◆ try_get_string()

◆ try_get_value()

◆ try_set_blob() [1/2]

◆ try_set_blob() [2/2]

◆ try_set_string()

◆ try_set_value()