nvs_get_str() function

get string value for given key These functions retrieve the data of an entry, given its key. If key does not exist, or the requested variable type doesn't match the type which was used when setting a value, an error is returned. In case of any error, out_value is not modified. All functions expect out_value to be a pointer to an already allocated variable of the given type. nvs_get_str and nvs_get_blob functions support WinAPI-style length queries. To get the size necessary to store the value, call nvs_get_str or nvs_get_blob with zero out_value and non-zero pointer to length. Variable pointed to by length argument will be set to the required length. For nvs_get_str, this length includes the zero terminator. When calling nvs_get_str and nvs_get_blob with non-zero out_value, length has to be non-zero and has to point to the length available in out_value. It is suggested that nvs_get/set_str is used for zero-terminated C strings, and nvs_get/set_blob used for arbitrary data structures.

{c}
 // Example (without error checking) of using nvs_get_str to get a string into dynamic array:
 size_t required_size;
 nvs_get_str(my_handle, "server_name", NULL, &required_size);
 char* server_name = malloc(required_size);
 nvs_get_str(my_handle, "server_name", server_name, &required_size);
 // Example (without error checking) of using nvs_get_blob to get a binary data
 into a static array:
 uint8_t mac_addr[6];
 size_t size = sizeof(mac_addr);
 nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
 

Syntax

Show:

Summary

Declaration

Definition

from nvs.h:494

esp_err_t nvs_get_str (nvs_handle_t handle, const char* key, char* out_value, size_t* length);

Implemented in nvs_api.cpp:529

Arguments

Argument

Description

handle

Handle obtained from nvs_open function.

key

Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.

out_value

Pointer to the output value. May be NULL for nvs_get_str and nvs_get_blob, in this case required length will be returned in length argument.

length

A non-zero pointer to the variable holding the length of out_value. In case out_value a zero, will be set to the length required to hold the value. In case out_value is not zero, will be set to the actual length of the value written. For nvs_get_str this includes zero terminator.

Return value

- ESP_OK if the value was retrieved successfully - ESP_FAIL if there is an internal error; most likely due to corrupted NVS partition (only if NVS assertion checks are disabled) - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints - ESP_ERR_NVS_INVALID_LENGTH if \c length is not sufficient to store data