这是最新(主)开发分支的文档。如果您正在查找以前版本的文档，使用左侧的下拉菜单选择所需的版本。

NVS API 参考

Macros

WM_NVS_DEF_PARTITION

nvs default partition name

WM_NVS_MAX_HANDLE_NUM

nvs handle max num Max num of nvs handle

WM_NVS_MAX_KEY_LEN

nvs key or group name max size Max size of nvs key, maximum 15 valid characters support, not include ‘\0’

WM_NVS_BLOB_MIN_SEG_SIZE

Mininum BLOB segment size, Not include item segment header.

WM_NVS_ERR_BASE

nvs error code

Base number of error codes

WM_NVS_ERR_OK

OK

WM_NVS_ERR_FAIL

failure

WM_NVS_ERR_INVALID_PARAM

invalid params

WM_NVS_ERR_NOT_INIT

The nvs is not initialized

WM_NVS_ERR_AREADY_INIT

The nvs is aready initialized

WM_NVS_ERR_NO_MEM

No enough memory

WM_NVS_ERR_NOT_FOUND

gourp or key not found

WM_NVS_ERR_READ_ONLY

partition is read only

WM_NVS_ERR_NO_SPACE

no enough space for saving

WM_NVS_ERR_INVALID_HANDLE

invalid handle

WM_NVS_ERR_SECTOR_FULL

sector is full

WM_NVS_ERR_INVALID_LENGTH

invalid data length

WM_NVS_ERR_VALUE_TOO_LONG

Value is too long

WM_NVS_ERR_CALL_IN_ISR

call in isr error

Enumerations

enum wm_nvs_open_mode_t

nvs open mode

Values:

enumerator WM_NVS_OP_READ_ONLY

read only mode

enumerator WM_NVS_OP_READ_WRITE

read and write mode

enumerator WM_NVS_OP_MAX
enum wm_nvs_type_t

nvs item data type

Values:

enumerator WM_NVS_TYPE_ANY

any type

enumerator WM_NVS_TYPE_STRING

string end with ‘\0’, max length 4031

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 data

enumerator WM_NVS_TYPE_BINARY

small binary data, size from 1~4032, not split to segments

enumerator WM_NVS_TYPE_BLOB

Binary Large OBject, It will be divided into multiple segments (1~127) for storage. Except the last piece, other segments are no less than 512 bytes. In addition, a description item will also be stored ,all the size no larger than 512064

enumerator WM_NVS_TYPE_MAX

Structures

typedef void *wm_nvs_handle_t

nvs handle , handle read and write items

typedef struct wm_nvs_entry_iterator_t *wm_nvs_iterator_t

iterator , handle for poll all nvs items

struct wm_nvs_entry_t

iterator entry information

Public Members

char group[15 + 1]

item group

char key[15 + 1]

item key

wm_nvs_type_t type

item type

uint8_t group_id

group id

size_t length

data length

struct wm_nvs_status_t

nvs status

Public Members

uint32_t total_size

total size

uint32_t using_size

using item size

uint32_t droped_size

drop item size

uint32_t free_size

free size

uint8_t group_num

num of groups

uint8_t handle_num

num of the handles

Functions

int wm_nvs_init(const char *partition_name)

Initialize nvs.

备注

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

参数:

partition_name – [in] nvs partition name

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_NO_MEM: no memery

  • WM_NVS_ERR_FAIL: failed

int wm_nvs_deinit(const char *partition_name)

Deinitialize nvs.

备注

The handle open by the api wm_nvs_open must be closed before wm_nvs_deinit called.

参数:

partition_name – [in] nvs partition name

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

int wm_nvs_erase(const char *partition_name)

erase the whole nvs partition

警告

All the data in the partition will be lost after wm_nvs_erase called. wm_nvs_deinit shoud be called first if the partition is initialized. It is usually called when setting factory recovery. It is better to reboot the system after calling this interface.

参数:

partition_name – [in] nvs partition name

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

int wm_nvs_print(const char *partition_name, const char *group_name)

Show all nvs information.

参数:

  • partition_name – [in] nvs partition name

  • group_name – [in] nvs group name, NULL for all group in partition

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

int wm_nvs_open(const char *partition_name, const char *group_name, wm_nvs_open_mode_t mode, wm_nvs_handle_t *handle)

open nvs operation handle

备注

shoud be closed by wm_nvs_close if it is not used.

参数:

  • partition_name – [in] nvs partition name, it will use default nvs partition if partition_name is null.

  • group_name – [in] nvs group name, max characters is 15 .

  • mode – [in] read write or only read, wm_nvs_open_mode_t

  • handle – [out] nvs operation handle

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

int wm_nvs_close(wm_nvs_handle_t handle)

close nvs operation handle

参数:

handle – [in] nvs operation handle,obtained from wm_nvs_open.

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

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

Get string by key name.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] string data

  • length – [inout] input out_value buffer size, output real value size return WM_NVS_ERR_INVALID_PARAM if buf is not enough; “hello” need 6 bytes, the out_value will be: “hello”\0

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Save string data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [out] string data,must be end of \0

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_get_binary(wm_nvs_handle_t handle, const char *key, void *data, size_t *data_len)

Get small binary data.

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

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • data – [out] binary data

  • data_len – [inout] binary data length

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_NVS_ERR_NOT_FOUND item is not found

int wm_nvs_set_binary(wm_nvs_handle_t handle, const char *key, const void *data, size_t data_len)

Save small binary data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • data – [in] binary data

  • data_len – [in] binary data length

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

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

Get Binary Large OBject.

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

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • blob – [out] blob data

  • blob_len – [inout] blob data length

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Save binary data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • blob – [in] binary data

  • blob_len – [in] binary data length

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_i8(wm_nvs_handle_t handle, const char *key, int8_t value)

Save int8 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] int8 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_u8(wm_nvs_handle_t handle, const char *key, uint8_t value)

Save uint8 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] uint8 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_i16(wm_nvs_handle_t handle, const char *key, int16_t value)

Save int16 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] int16 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_u16(wm_nvs_handle_t handle, const char *key, uint16_t value)

Save uint16 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] uint16 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_i32(wm_nvs_handle_t handle, const char *key, int32_t value)

Save int32 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] int32 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_u32(wm_nvs_handle_t handle, const char *key, uint32_t value)

Save uint32 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] uint32 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_i64(wm_nvs_handle_t handle, const char *key, int64_t value)

Save int64 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] int64 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_u64(wm_nvs_handle_t handle, const char *key, uint64_t value)

Save uint64 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] uint64 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

int wm_nvs_set_float(wm_nvs_handle_t handle, const char *key, double value)

Save float data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • value – [in] float value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL save item fail

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

Get int8 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] int8 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get uint8 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] uint8 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get int16 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] int16 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get uint16 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] uint16 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get int32 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] int32 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get uint32 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] uint32 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get int64 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] int64 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get uint64 data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] uint64 value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

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

Get float data.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

  • out_value – [out] float value

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

int wm_nvs_del_key(wm_nvs_handle_t handle, const char *key)

Delete the nvs data for the key.

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs name

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND item is not found

int wm_nvs_del_group(wm_nvs_handle_t handle)

reset nvs. It is usually called at factory settings, and the system is restarted after the nvs reset.

警告

Calling this interface will clear all group data and cannot be recovered.

参数:

handle – [in] nvs operation handle,obtained from wm_nvs_open.

返回:

  • WM_NVS_ERR_OK: succeed

  • WM_NVS_ERR_FAIL: failed

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

find iterator, used for poll all or specified items.

备注

The output iterator handle must be release by wm_nvs_release_iterator

参数:

  • partition_name – [in] nvs partition name

  • group – [in] group name

  • type – [in] data type,WM_NVS_TYPE_ANY for all types

  • output_iterator – [out] iterator

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL fail

int wm_nvs_entry_find_by_handle(wm_nvs_handle_t handle, wm_nvs_type_t type, wm_nvs_iterator_t *output_iterator)

find iterator, used for poll all or specified items.

备注

The output iterator handle must be release by wm_nvs_release_iterator

参数:

  • handle – [in] nvs operation handle, obtained from wm_nvs_open

  • type – [in] data type,WM_NVS_TYPE_ANY for all types

  • output_iterator – [out] iterator

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL fail

int wm_nvs_entry_next(wm_nvs_iterator_t *iterator)

change to next iterator

参数:

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

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL iterator end or fail

int wm_nvs_entry_info(wm_nvs_iterator_t iterator, wm_nvs_entry_t *info)

get iterator info

参数:

  • iterator – [in] iterator

  • info – [out] iterator entry information

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL fail

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

get iterator data

参数:

  • iterator – [in] iterator

  • data – [out] iterator entry information

  • data_len – [inout] data len, input buffer len, output real len, return WM_NVS_ERR_INVALID_PARAM if input data_len is not enough

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_FAIL fail

int wm_nvs_release_iterator(wm_nvs_iterator_t iterator)

get iterator data

备注

iterator can be NULL

参数:

iterator – [in] iterator release iteraotr memory

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

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

get item type and size

参数:

  • handle – [in] nvs operation handle,obtained from wm_nvs_open.

  • key – [in] nvs item name

  • type – [out] data type

  • size – [out] data size

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error

  • WM_NVS_ERR_NOT_FOUND

int wm_nvs_get_status(const char *partition_name, wm_nvs_status_t *status)

get nvs status

参数:

  • partition_name – [out] nvs partition name

  • status – [out] nvs status, wm_nvs_status_t

返回:

  • WM_NVS_ERR_OK on success

  • WM_NVS_ERR_INVALID_PARAM param error