The latest development version of this page may be more current than this released 0.4.3 version.

NVS API Reference

Data structure

nvs module

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.

Defines

WM_NVS_MAX_KEY_LEN: nvs key max size Max size of nvs key, use the config size of CONFIG_NVS_ITEM_NAME_MAX_SIZE

Typedefs

typedef struct wm_nvs_entry_iterator_t *wm_nvs_iterator_t: iterator , handle for poll all nvs items

Enums

enum wm_nvs_type_t

nvs item data type

Values:

enumerator WM_NVS_TYPE_ANY: any type

enumerator WM_NVS_TYPE_STRING: string with 0

enumerator WM_NVS_TYPE_RAW: raw data

enumerator WM_NVS_TYPE_INT8: int8_t

enumerator WM_NVS_TYPE_UINT8: uint8_t

enumerator WM_NVS_TYPE_INT16: int16_t

enumerator WM_NVS_TYPE_UINT16: uint16_t

enumerator WM_NVS_TYPE_INT32: int32_t

enumerator WM_NVS_TYPE_UINT32: uint32_t

enumerator WM_NVS_TYPE_INT64: int64_t

enumerator WM_NVS_TYPE_UINT64: uint64_t

enumerator WM_NVS_TYPE_DOUBLE: float

Functions

int wm_nvs_init(void)

Initialize nvs.

Attention: This API must be called before all other nvs API can be called

Returns:

WM_ERR_SUCCESS: succeed
WM_ERR_NO_MEM: no memery
WM_ERR_FAILED: failed

int wm_nvs_get_str(const char *key, char *out_value, size_t *length)

Set string data.

Parameters:

key – [in] nvs name
out_value – [out] string data
length – [inout] input out_value buffer size, output real value size return WM_ERR_INVALID_PARAM if buf is not enough; “hello” need 6 bytes, the out_value will be: “hello”\0

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error or buffer is not enough
WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_str(const char *key, const char *value)

Save string data.

Parameters:

key – [in] nvs name
value – [out] string data,must be end of \0

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_get_blob(const char *key, void *blob, size_t *blob_len)

Get binary data.

Notes: If blob is empty, blob_len returns the actual length to hold the data.

Parameters:

key – [in] nvs name
blob – [out] binary data
blob_len – [inout] binary data length

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error or buffer is not enough
WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_blob(const char *key, const void *blob, size_t blob_len)

Save binary data.

Parameters:

key – [in] nvs name
blob – [in] binary data
blob_len – [in] binary data length

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_del(const char *key)

Delete the nvs data for the key.

Parameters:

key – [in] nvs name

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_reset(void)

reset nvs

Attention: Calling this api removes all configurations

Returns:

WM_ERR_SUCCESS: succeed
WM_ERR_FAILED: failed

void wm_nvs_print(void)

Show all nvs information.

Returns:: None

int wm_nvs_set_i8(const char *key, int8_t value)

Save int8 data.

Parameters:

key – [in] nvs name
value – [in] int8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u8(const char *key, uint8_t value)

Save uint8 data.

Parameters:

key – [in] nvs name
value – [in] uint8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i16(const char *key, int16_t value)

Save int16 data.

Parameters:

key – [in] nvs name
value – [in] int16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u16(const char *key, uint16_t value)

Save uint16 data.

Parameters:

key – [in] nvs name
value – [in] uint16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i32(const char *key, int32_t value)

Save int32 data.

Parameters:

key – [in] nvs name
value – [in] int32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u32(const char *key, uint32_t value)

Save uint32 data.

Parameters:

key – [in] nvs name
value – [in] uint32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i64(const char *key, int64_t value)

Save int64 data.

Parameters:

key – [in] nvs name
value – [in] int64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u64(const char *key, uint64_t value)

Save uint64 data.

Parameters:

key – [in] nvs name
value – [in] uint64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_float(const char *key, double value)

Save float data.

Parameters:

key – [in] nvs name
value – [in] float value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_get_i8(const char *key, int8_t *out_value)

Get int8 data.

Parameters:

key – [in] nvs name
out_value – [out] int8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u8(const char *key, uint8_t *out_value)

Get uint8 data.

Parameters:

key – [in] nvs name
out_value – [out] uint8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i16(const char *key, int16_t *out_value)

Get int16 data.

Parameters:

key – [in] nvs name
out_value – [out] int16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u16(const char *key, uint16_t *out_value)

Get uint16 data.

Parameters:

key – [in] nvs name
out_value – [out] uint16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i32(const char *key, int32_t *out_value)

Get int32 data.

Parameters:

key – [in] nvs name
out_value – [out] int32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u32(const char *key, uint32_t *out_value)

Get uint32 data.

Parameters:

key – [in] nvs name
out_value – [out] uint32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i64(const char *key, int64_t *out_value)

Get int64 data.

Parameters:

key – [in] nvs name
out_value – [out] int64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u64(const char *key, uint64_t *out_value)

Get uint64 data.

Parameters:

key – [in] nvs name
out_value – [out] uint64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_float(const char *key, double *out_value)

Get float data.

Parameters:

key – [in] nvs name
out_value – [out] float value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_entry_find(const char *prefix, wm_nvs_type_t type, wm_nvs_iterator_t *output_iterator)

find iterator, used for poll all or specified items note: it will lock nvs until wm_nvs_entry_next end or wm_nvs_release_iterator is called. only current task can access before unlock.

Parameters:

prefix – [in] nvs key name prefix,NULL for all keys
type – [in] data type,WM_NVS_TYPE_ANY for all types
output_iterator – [out] iterator

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_entry_next(wm_nvs_iterator_t *iterator)

change to next iterator

Parameters:

iterator – [inout] iterator to next item out iterator: ! NULL : next item NULL : iterator end, the memery is released, the mutex is unlocked.

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL iterator end or fail

int wm_nvs_entry_info(wm_nvs_iterator_t iterator, wm_nvs_entry_t *info)

get iterator info

Parameters:

iterator – [in] iterator
info – [out] iterator entry information

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_entry_data(wm_nvs_iterator_t iterator, void *data, size_t *data_len)

get iterator data

Parameters:

iterator – [in] iterator
data – [out] iterator entry information
data_len – [inout] data len, input buffer len, output real len, return WM_ERR_INVALID_PARAM if input data_len is not enough

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_release_iterator(wm_nvs_iterator_t iterator)

get iterator data

Parameters:

iterator – [in] iterator release memory and unlock

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error

int wm_nvs_get_info(const char *key, wm_nvs_type_t *type, size_t *size)

get item type and size

Parameters:

key – [in] nvs item name
type – [out] data type, wm_nvs_type_t
size – [out] data size

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND

int wm_nvs_get_status(wm_nvs_status_t *status)

get nvs status

Parameters:

status – [out] nvs status, wm_nvs_status_t

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error

struct wm_nvs_entry_t

iterator entry information

Public Members

wm_nvs_type_t type: data type

const char *key: item key

size_t data_len: data length

struct wm_nvs_status_t

nvs status

Public Members

uint32_t total_size: total size

uint32_t total_free: total free size

uint32_t max_free_block_size: max free block size

uint16_t sector_num: sector num

uint16_t item_num: save item num

Interface definition:

int wm_nvs_init(void)

Initialize nvs.

Attention: This API must be called before all other nvs API can be called

Returns:

WM_ERR_SUCCESS: succeed
WM_ERR_NO_MEM: no memery
WM_ERR_FAILED: failed

int wm_nvs_get_str(const char *key, char *out_value, size_t *length)

Set string data.

Parameters:

key – [in] nvs name
out_value – [out] string data
length – [inout] input out_value buffer size, output real value size return WM_ERR_INVALID_PARAM if buf is not enough; “hello” need 6 bytes, the out_value will be: “hello”\0

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error or buffer is not enough
WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_str(const char *key, const char *value)

Save string data.

Parameters:

key – [in] nvs name
value – [out] string data,must be end of \0

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_get_blob(const char *key, void *blob, size_t *blob_len)

Get binary data.

Notes: If blob is empty, blob_len returns the actual length to hold the data.

Parameters:

key – [in] nvs name
blob – [out] binary data
blob_len – [inout] binary data length

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error or buffer is not enough
WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_blob(const char *key, const void *blob, size_t blob_len)

Save binary data.

Parameters:

key – [in] nvs name
blob – [in] binary data
blob_len – [in] binary data length

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_del(const char *key)

Delete the nvs data for the key.

Parameters:

key – [in] nvs name

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_reset(void)

reset nvs

Attention: Calling this api removes all configurations

Returns:

WM_ERR_SUCCESS: succeed
WM_ERR_FAILED: failed

void wm_nvs_print(void)

Show all nvs information.

Returns:: None

int wm_nvs_set_i8(const char *key, int8_t value)

Save int8 data.

Parameters:

key – [in] nvs name
value – [in] int8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u8(const char *key, uint8_t value)

Save uint8 data.

Parameters:

key – [in] nvs name
value – [in] uint8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i16(const char *key, int16_t value)

Save int16 data.

Parameters:

key – [in] nvs name
value – [in] int16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u16(const char *key, uint16_t value)

Save uint16 data.

Parameters:

key – [in] nvs name
value – [in] uint16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i32(const char *key, int32_t value)

Save int32 data.

Parameters:

key – [in] nvs name
value – [in] int32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u32(const char *key, uint32_t value)

Save uint32 data.

Parameters:

key – [in] nvs name
value – [in] uint32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_i64(const char *key, int64_t value)

Save int64 data.

Parameters:

key – [in] nvs name
value – [in] int64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_u64(const char *key, uint64_t value)

Save uint64 data.

Parameters:

key – [in] nvs name
value – [in] uint64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_set_float(const char *key, double value)

Save float data.

Parameters:

key – [in] nvs name
value – [in] float value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAILED save item fail

int wm_nvs_get_i8(const char *key, int8_t *out_value)

Get int8 data.

Parameters:

key – [in] nvs name
out_value – [out] int8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u8(const char *key, uint8_t *out_value)

Get uint8 data.

Parameters:

key – [in] nvs name
out_value – [out] uint8 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i16(const char *key, int16_t *out_value)

Get int16 data.

Parameters:

key – [in] nvs name
out_value – [out] int16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u16(const char *key, uint16_t *out_value)

Get uint16 data.

Parameters:

key – [in] nvs name
out_value – [out] uint16 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i32(const char *key, int32_t *out_value)

Get int32 data.

Parameters:

key – [in] nvs name
out_value – [out] int32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u32(const char *key, uint32_t *out_value)

Get uint32 data.

Parameters:

key – [in] nvs name
out_value – [out] uint32 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i64(const char *key, int64_t *out_value)

Get int64 data.

Parameters:

key – [in] nvs name
out_value – [out] int64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u64(const char *key, uint64_t *out_value)

Get uint64 data.

Parameters:

key – [in] nvs name
out_value – [out] uint64 value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_float(const char *key, double *out_value)

Get float data.

Parameters:

key – [in] nvs name
out_value – [out] float value

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND item is not found

int wm_nvs_entry_find(const char *prefix, wm_nvs_type_t type, wm_nvs_iterator_t *output_iterator)

find iterator, used for poll all or specified items note: it will lock nvs until wm_nvs_entry_next end or wm_nvs_release_iterator is called. only current task can access before unlock.

Parameters:

prefix – [in] nvs key name prefix,NULL for all keys
type – [in] data type,WM_NVS_TYPE_ANY for all types
output_iterator – [out] iterator

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_entry_next(wm_nvs_iterator_t *iterator)

change to next iterator

Parameters:

iterator – [inout] iterator to next item out iterator: ! NULL : next item NULL : iterator end, the memery is released, the mutex is unlocked.

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL iterator end or fail

int wm_nvs_entry_info(wm_nvs_iterator_t iterator, wm_nvs_entry_t *info)

get iterator info

Parameters:

iterator – [in] iterator
info – [out] iterator entry information

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_entry_data(wm_nvs_iterator_t iterator, void *data, size_t *data_len)

get iterator data

Parameters:

iterator – [in] iterator
data – [out] iterator entry information
data_len – [inout] data len, input buffer len, output real len, return WM_ERR_INVALID_PARAM if input data_len is not enough

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_FAIL fail

int wm_nvs_release_iterator(wm_nvs_iterator_t iterator)

get iterator data

Parameters:

iterator – [in] iterator release memory and unlock

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error

int wm_nvs_get_info(const char *key, wm_nvs_type_t *type, size_t *size)

get item type and size

Parameters:

key – [in] nvs item name
type – [out] data type, wm_nvs_type_t
size – [out] data size

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error
WM_ERR_NOT_FOUND

int wm_nvs_get_status(wm_nvs_status_t *status)

get nvs status

Parameters:

status – [out] nvs status, wm_nvs_status_t

Returns:

WM_ERR_SUCCESS on success
WM_ERR_INVALID_PARAM param error