1 /* 2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef ESP_NVS_H 7 #define ESP_NVS_H 8 9 #include <stdint.h> 10 #include <stddef.h> 11 #include <stdbool.h> 12 #include "esp_attr.h" 13 #include "esp_err.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * Opaque pointer type representing non-volatile storage handle 21 */ 22 typedef uint32_t nvs_handle_t; 23 24 /* 25 * Pre-IDF V4.0 uses nvs_handle, so leaving the original typedef here for compatibility. 26 */ 27 typedef nvs_handle_t nvs_handle IDF_DEPRECATED("Replace with nvs_handle_t"); 28 29 #define ESP_ERR_NVS_BASE 0x1100 /*!< Starting number of error codes */ 30 #define ESP_ERR_NVS_NOT_INITIALIZED (ESP_ERR_NVS_BASE + 0x01) /*!< The storage driver is not initialized */ 31 #define ESP_ERR_NVS_NOT_FOUND (ESP_ERR_NVS_BASE + 0x02) /*!< Id namespace doesn’t exist yet and mode is NVS_READONLY */ 32 #define ESP_ERR_NVS_TYPE_MISMATCH (ESP_ERR_NVS_BASE + 0x03) /*!< The type of set or get operation doesn't match the type of value stored in NVS */ 33 #define ESP_ERR_NVS_READ_ONLY (ESP_ERR_NVS_BASE + 0x04) /*!< Storage handle was opened as read only */ 34 #define ESP_ERR_NVS_NOT_ENOUGH_SPACE (ESP_ERR_NVS_BASE + 0x05) /*!< There is not enough space in the underlying storage to save the value */ 35 #define ESP_ERR_NVS_INVALID_NAME (ESP_ERR_NVS_BASE + 0x06) /*!< Namespace name doesn’t satisfy constraints */ 36 #define ESP_ERR_NVS_INVALID_HANDLE (ESP_ERR_NVS_BASE + 0x07) /*!< Handle has been closed or is NULL */ 37 #define ESP_ERR_NVS_REMOVE_FAILED (ESP_ERR_NVS_BASE + 0x08) /*!< 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. */ 38 #define ESP_ERR_NVS_KEY_TOO_LONG (ESP_ERR_NVS_BASE + 0x09) /*!< Key name is too long */ 39 #define ESP_ERR_NVS_PAGE_FULL (ESP_ERR_NVS_BASE + 0x0a) /*!< Internal error; never returned by nvs API functions */ 40 #define ESP_ERR_NVS_INVALID_STATE (ESP_ERR_NVS_BASE + 0x0b) /*!< NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry. */ 41 #define ESP_ERR_NVS_INVALID_LENGTH (ESP_ERR_NVS_BASE + 0x0c) /*!< String or blob length is not sufficient to store data */ 42 #define ESP_ERR_NVS_NO_FREE_PAGES (ESP_ERR_NVS_BASE + 0x0d) /*!< 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. */ 43 #define ESP_ERR_NVS_VALUE_TOO_LONG (ESP_ERR_NVS_BASE + 0x0e) /*!< String or blob length is longer than supported by the implementation */ 44 #define ESP_ERR_NVS_PART_NOT_FOUND (ESP_ERR_NVS_BASE + 0x0f) /*!< Partition with specified name is not found in the partition table */ 45 46 #define ESP_ERR_NVS_NEW_VERSION_FOUND (ESP_ERR_NVS_BASE + 0x10) /*!< NVS partition contains data in new format and cannot be recognized by this version of code */ 47 #define ESP_ERR_NVS_XTS_ENCR_FAILED (ESP_ERR_NVS_BASE + 0x11) /*!< XTS encryption failed while writing NVS entry */ 48 #define ESP_ERR_NVS_XTS_DECR_FAILED (ESP_ERR_NVS_BASE + 0x12) /*!< XTS decryption failed while reading NVS entry */ 49 #define ESP_ERR_NVS_XTS_CFG_FAILED (ESP_ERR_NVS_BASE + 0x13) /*!< XTS configuration setting failed */ 50 #define ESP_ERR_NVS_XTS_CFG_NOT_FOUND (ESP_ERR_NVS_BASE + 0x14) /*!< XTS configuration not found */ 51 #define ESP_ERR_NVS_ENCR_NOT_SUPPORTED (ESP_ERR_NVS_BASE + 0x15) /*!< NVS encryption is not supported in this version */ 52 #define ESP_ERR_NVS_KEYS_NOT_INITIALIZED (ESP_ERR_NVS_BASE + 0x16) /*!< NVS key partition is uninitialized */ 53 #define ESP_ERR_NVS_CORRUPT_KEY_PART (ESP_ERR_NVS_BASE + 0x17) /*!< NVS key partition is corrupt */ 54 #define ESP_ERR_NVS_WRONG_ENCRYPTION (ESP_ERR_NVS_BASE + 0x19) /*!< NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption works differently. */ 55 56 #define ESP_ERR_NVS_CONTENT_DIFFERS (ESP_ERR_NVS_BASE + 0x18) /*!< Internal error; never returned by nvs API functions. NVS key is different in comparison */ 57 58 #define NVS_DEFAULT_PART_NAME "nvs" /*!< Default partition name of the NVS partition in the partition table */ 59 60 #define NVS_PART_NAME_MAX_SIZE 16 /*!< maximum length of partition name (excluding null terminator) */ 61 #define NVS_KEY_NAME_MAX_SIZE 16 /*!< Maximal length of NVS key name (including null terminator) */ 62 63 /** 64 * @brief Mode of opening the non-volatile storage 65 */ 66 typedef enum { 67 NVS_READONLY, /*!< Read only */ 68 NVS_READWRITE /*!< Read and write */ 69 } nvs_open_mode_t; 70 71 /* 72 * Pre-IDF V4.0 uses nvs_open_mode, so leaving the original typedef here for compatibility. 73 */ 74 typedef nvs_open_mode_t nvs_open_mode IDF_DEPRECATED("Replace with nvs_open_mode_t"); 75 76 77 /** 78 * @brief Types of variables 79 * 80 */ 81 typedef enum { 82 NVS_TYPE_U8 = 0x01, /*!< Type uint8_t */ 83 NVS_TYPE_I8 = 0x11, /*!< Type int8_t */ 84 NVS_TYPE_U16 = 0x02, /*!< Type uint16_t */ 85 NVS_TYPE_I16 = 0x12, /*!< Type int16_t */ 86 NVS_TYPE_U32 = 0x04, /*!< Type uint32_t */ 87 NVS_TYPE_I32 = 0x14, /*!< Type int32_t */ 88 NVS_TYPE_U64 = 0x08, /*!< Type uint64_t */ 89 NVS_TYPE_I64 = 0x18, /*!< Type int64_t */ 90 NVS_TYPE_STR = 0x21, /*!< Type string */ 91 NVS_TYPE_BLOB = 0x42, /*!< Type blob */ 92 NVS_TYPE_ANY = 0xff /*!< Must be last */ 93 } nvs_type_t; 94 95 /** 96 * @brief information about entry obtained from nvs_entry_info function 97 */ 98 typedef struct { 99 char namespace_name[16]; /*!< Namespace to which key-value belong */ 100 char key[NVS_KEY_NAME_MAX_SIZE]; /*!< Key of stored key-value pair */ 101 nvs_type_t type; /*!< Type of stored key-value pair */ 102 } nvs_entry_info_t; 103 104 /** 105 * Opaque pointer type representing iterator to nvs entries 106 */ 107 typedef struct nvs_opaque_iterator_t *nvs_iterator_t; 108 109 /** 110 * @brief Open non-volatile storage with a given namespace from the default NVS partition 111 * 112 * Multiple internal ESP-IDF and third party application modules can store 113 * their key-value pairs in the NVS module. In order to reduce possible 114 * conflicts on key names, each module can use its own namespace. 115 * The default NVS partition is the one that is labelled "nvs" in the partition 116 * table. 117 * 118 * @param[in] name Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 119 * @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will 120 * open a handle for reading only. All write requests will 121 * be rejected for this handle. 122 * @param[out] out_handle If successful (return code is zero), handle will be 123 * returned in this argument. 124 * 125 * @return 126 * - ESP_OK if storage handle was opened successfully 127 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized 128 * - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "nvs" is not found 129 * - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and 130 * mode is NVS_READONLY 131 * - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints 132 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 133 * - other error codes from the underlying storage driver 134 */ 135 esp_err_t nvs_open(const char* name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle); 136 137 /** 138 * @brief Open non-volatile storage with a given namespace from specified partition 139 * 140 * The behaviour is same as nvs_open() API. However this API can operate on a specified NVS 141 * partition instead of default NVS partition. Note that the specified partition must be registered 142 * with NVS using nvs_flash_init_partition() API. 143 * 144 * @param[in] part_name Label (name) of the partition of interest for object read/write/erase 145 * @param[in] name Namespace name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 146 * @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will 147 * open a handle for reading only. All write requests will 148 * be rejected for this handle. 149 * @param[out] out_handle If successful (return code is zero), handle will be 150 * returned in this argument. 151 * 152 * @return 153 * - ESP_OK if storage handle was opened successfully 154 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized 155 * - ESP_ERR_NVS_PART_NOT_FOUND if the partition with specified name is not found 156 * - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and 157 * mode is NVS_READONLY 158 * - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints 159 * - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures 160 * - other error codes from the underlying storage driver 161 */ 162 esp_err_t nvs_open_from_partition(const char *part_name, const char* name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle); 163 164 /**@{*/ 165 /** 166 * @brief set int8_t value for given key 167 * 168 * Set value for the key, given its name. Note that the actual storage will not be updated 169 * until \c nvs_commit is called. 170 * 171 * @param[in] handle Handle obtained from nvs_open function. 172 * Handles that were opened read only cannot be used. 173 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 174 * @param[in] value The value to set. 175 * 176 * @return 177 * - ESP_OK if value was set successfully 178 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 179 * - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only 180 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 181 * - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the 182 * underlying storage to save the value 183 * - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash 184 * write operation has failed. The value was written however, and 185 * update will be finished after re-initialization of nvs, provided that 186 * flash operation doesn't fail again. 187 */ 188 esp_err_t nvs_set_i8 (nvs_handle_t handle, const char* key, int8_t value); 189 190 /** 191 * @brief set uint8_t value for given key 192 * 193 * This function is the same as \c nvs_set_i8 except for the data type. 194 */ 195 esp_err_t nvs_set_u8 (nvs_handle_t handle, const char* key, uint8_t value); 196 197 /** 198 * @brief set int16_t value for given key 199 * 200 * This function is the same as \c nvs_set_i8 except for the data type. 201 */ 202 esp_err_t nvs_set_i16 (nvs_handle_t handle, const char* key, int16_t value); 203 204 /** 205 * @brief set uint16_t value for given key 206 * 207 * This function is the same as \c nvs_set_i8 except for the data type. 208 */ 209 esp_err_t nvs_set_u16 (nvs_handle_t handle, const char* key, uint16_t value); 210 211 /** 212 * @brief set int32_t value for given key 213 * 214 * This function is the same as \c nvs_set_i8 except for the data type. 215 */ 216 esp_err_t nvs_set_i32 (nvs_handle_t handle, const char* key, int32_t value); 217 218 /** 219 * @brief set uint32_t value for given key 220 * 221 * This function is the same as \c nvs_set_i8 except for the data type. 222 */ 223 esp_err_t nvs_set_u32 (nvs_handle_t handle, const char* key, uint32_t value); 224 225 /** 226 * @brief set int64_t value for given key 227 * 228 * This function is the same as \c nvs_set_i8 except for the data type. 229 */ 230 esp_err_t nvs_set_i64 (nvs_handle_t handle, const char* key, int64_t value); 231 232 /** 233 * @brief set uint64_t value for given key 234 * 235 * This function is the same as \c nvs_set_i8 except for the data type. 236 */ 237 esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value); 238 239 /** 240 * @brief set string for given key 241 * 242 * Set value for the key, given its name. Note that the actual storage will not be updated 243 * until \c nvs_commit is called. 244 * 245 * @param[in] handle Handle obtained from nvs_open function. 246 * Handles that were opened read only cannot be used. 247 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 248 * @param[in] value The value to set. 249 * For strings, the maximum length (including null character) is 250 * 4000 bytes, if there is one complete page free for writing. 251 * This decreases, however, if the free space is fragmented. 252 * 253 * @return 254 * - ESP_OK if value was set successfully 255 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 256 * - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only 257 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 258 * - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the 259 * underlying storage to save the value 260 * - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash 261 * write operation has failed. The value was written however, and 262 * update will be finished after re-initialization of nvs, provided that 263 * flash operation doesn't fail again. 264 * - ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long 265 */ 266 esp_err_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value); 267 /**@}*/ 268 269 /** 270 * @brief set variable length binary value for given key 271 * 272 * This family of functions set value for the key, given its name. Note that 273 * actual storage will not be updated until nvs_commit function is called. 274 * 275 * @param[in] handle Handle obtained from nvs_open function. 276 * Handles that were opened read only cannot be used. 277 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 278 * @param[in] value The value to set. 279 * @param[in] length length of binary value to set, in bytes; Maximum length is 280 * 508000 bytes or (97.6% of the partition size - 4000) bytes 281 * whichever is lower. 282 * 283 * @return 284 * - ESP_OK if value was set successfully 285 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 286 * - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only 287 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 288 * - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the 289 * underlying storage to save the value 290 * - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash 291 * write operation has failed. The value was written however, and 292 * update will be finished after re-initialization of nvs, provided that 293 * flash operation doesn't fail again. 294 * - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long 295 */ 296 esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value, size_t length); 297 298 /**@{*/ 299 /** 300 * @brief get int8_t value for given key 301 * 302 * These functions retrieve value for the key, given its name. If \c key does not 303 * exist, or the requested variable type doesn't match the type which was used 304 * when setting a value, an error is returned. 305 * 306 * In case of any error, out_value is not modified. 307 * 308 * \c out_value has to be a pointer to an already allocated variable of the given type. 309 * 310 * \code{c} 311 * // Example of using nvs_get_i32: 312 * int32_t max_buffer_size = 4096; // default value 313 * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size); 314 * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND); 315 * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still 316 * // have its default value. 317 * 318 * \endcode 319 * 320 * @param[in] handle Handle obtained from nvs_open function. 321 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 322 * @param out_value Pointer to the output value. 323 * May be NULL for nvs_get_str and nvs_get_blob, in this 324 * case required length will be returned in length argument. 325 * 326 * @return 327 * - ESP_OK if the value was retrieved successfully 328 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 329 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 330 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 331 * - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data 332 */ 333 esp_err_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value); 334 335 /** 336 * @brief get uint8_t value for given key 337 * 338 * This function is the same as \c nvs_get_i8 except for the data type. 339 */ 340 esp_err_t nvs_get_u8 (nvs_handle_t handle, const char* key, uint8_t* out_value); 341 342 /** 343 * @brief get int16_t value for given key 344 * 345 * This function is the same as \c nvs_get_i8 except for the data type. 346 */ 347 esp_err_t nvs_get_i16 (nvs_handle_t handle, const char* key, int16_t* out_value); 348 349 /** 350 * @brief get uint16_t value for given key 351 * 352 * This function is the same as \c nvs_get_i8 except for the data type. 353 */ 354 esp_err_t nvs_get_u16 (nvs_handle_t handle, const char* key, uint16_t* out_value); 355 356 /** 357 * @brief get int32_t value for given key 358 * 359 * This function is the same as \c nvs_get_i8 except for the data type. 360 */ 361 esp_err_t nvs_get_i32 (nvs_handle_t handle, const char* key, int32_t* out_value); 362 363 /** 364 * @brief get uint32_t value for given key 365 * 366 * This function is the same as \c nvs_get_i8 except for the data type. 367 */ 368 esp_err_t nvs_get_u32 (nvs_handle_t handle, const char* key, uint32_t* out_value); 369 370 /** 371 * @brief get int64_t value for given key 372 * 373 * This function is the same as \c nvs_get_i8 except for the data type. 374 */ 375 esp_err_t nvs_get_i64 (nvs_handle_t handle, const char* key, int64_t* out_value); 376 377 /** 378 * @brief get uint64_t value for given key 379 * 380 * This function is the same as \c nvs_get_i8 except for the data type. 381 */ 382 esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value); 383 /**@}*/ 384 385 /**@{*/ 386 /** 387 * @brief get string value for given key 388 * 389 * These functions retrieve the data of an entry, given its key. If key does not 390 * exist, or the requested variable type doesn't match the type which was used 391 * when setting a value, an error is returned. 392 * 393 * In case of any error, out_value is not modified. 394 * 395 * All functions expect out_value to be a pointer to an already allocated variable 396 * of the given type. 397 * 398 * nvs_get_str and nvs_get_blob functions support WinAPI-style length queries. 399 * To get the size necessary to store the value, call nvs_get_str or nvs_get_blob 400 * with zero out_value and non-zero pointer to length. Variable pointed to 401 * by length argument will be set to the required length. For nvs_get_str, 402 * this length includes the zero terminator. When calling nvs_get_str and 403 * nvs_get_blob with non-zero out_value, length has to be non-zero and has to 404 * point to the length available in out_value. 405 * It is suggested that nvs_get/set_str is used for zero-terminated C strings, and 406 * nvs_get/set_blob used for arbitrary data structures. 407 * 408 * \code{c} 409 * // Example (without error checking) of using nvs_get_str to get a string into dynamic array: 410 * size_t required_size; 411 * nvs_get_str(my_handle, "server_name", NULL, &required_size); 412 * char* server_name = malloc(required_size); 413 * nvs_get_str(my_handle, "server_name", server_name, &required_size); 414 * 415 * // Example (without error checking) of using nvs_get_blob to get a binary data 416 * into a static array: 417 * uint8_t mac_addr[6]; 418 * size_t size = sizeof(mac_addr); 419 * nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size); 420 * \endcode 421 * 422 * @param[in] handle Handle obtained from nvs_open function. 423 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 424 * @param[out] out_value Pointer to the output value. 425 * May be NULL for nvs_get_str and nvs_get_blob, in this 426 * case required length will be returned in length argument. 427 * @param[inout] length A non-zero pointer to the variable holding the length of out_value. 428 * In case out_value a zero, will be set to the length 429 * required to hold the value. In case out_value is not 430 * zero, will be set to the actual length of the value 431 * written. For nvs_get_str this includes zero terminator. 432 * 433 * @return 434 * - ESP_OK if the value was retrieved successfully 435 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 436 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 437 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 438 * - ESP_ERR_NVS_INVALID_LENGTH if \c length is not sufficient to store data 439 */ 440 esp_err_t nvs_get_str (nvs_handle_t handle, const char* key, char* out_value, size_t* length); 441 442 /** 443 * @brief get blob value for given key 444 * 445 * This function behaves the same as \c nvs_get_str, except for the data type. 446 */ 447 esp_err_t nvs_get_blob(nvs_handle_t handle, const char* key, void* out_value, size_t* length); 448 /**@}*/ 449 450 /** 451 * @brief Erase key-value pair with given key name. 452 * 453 * Note that actual storage may not be updated until nvs_commit function is called. 454 * 455 * @param[in] handle Storage handle obtained with nvs_open. 456 * Handles that were opened read only cannot be used. 457 * 458 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 459 * 460 * @return 461 * - ESP_OK if erase operation was successful 462 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 463 * - ESP_ERR_NVS_READ_ONLY if handle was opened as read only 464 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 465 * - other error codes from the underlying storage driver 466 */ 467 esp_err_t nvs_erase_key(nvs_handle_t handle, const char* key); 468 469 /** 470 * @brief Erase all key-value pairs in a namespace 471 * 472 * Note that actual storage may not be updated until nvs_commit function is called. 473 * 474 * @param[in] handle Storage handle obtained with nvs_open. 475 * Handles that were opened read only cannot be used. 476 * 477 * @return 478 * - ESP_OK if erase operation was successful 479 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 480 * - ESP_ERR_NVS_READ_ONLY if handle was opened as read only 481 * - other error codes from the underlying storage driver 482 */ 483 esp_err_t nvs_erase_all(nvs_handle_t handle); 484 485 /** 486 * @brief Write any pending changes to non-volatile storage 487 * 488 * After setting any values, nvs_commit() must be called to ensure changes are written 489 * to non-volatile storage. Individual implementations may write to storage at other times, 490 * but this is not guaranteed. 491 * 492 * @param[in] handle Storage handle obtained with nvs_open. 493 * Handles that were opened read only cannot be used. 494 * 495 * @return 496 * - ESP_OK if the changes have been written successfully 497 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 498 * - other error codes from the underlying storage driver 499 */ 500 esp_err_t nvs_commit(nvs_handle_t handle); 501 502 /** 503 * @brief Close the storage handle and free any allocated resources 504 * 505 * This function should be called for each handle opened with nvs_open once 506 * the handle is not in use any more. Closing the handle may not automatically 507 * write the changes to nonvolatile storage. This has to be done explicitly using 508 * nvs_commit function. 509 * Once this function is called on a handle, the handle should no longer be used. 510 * 511 * @param[in] handle Storage handle to close 512 */ 513 void nvs_close(nvs_handle_t handle); 514 515 /** 516 * @note Info about storage space NVS. 517 */ 518 typedef struct { 519 size_t used_entries; /**< Amount of used entries. */ 520 size_t free_entries; /**< Amount of free entries. */ 521 size_t total_entries; /**< Amount all available entries. */ 522 size_t namespace_count; /**< Amount name space. */ 523 } nvs_stats_t; 524 525 /** 526 * @brief Fill structure nvs_stats_t. It provides info about used memory the partition. 527 * 528 * This function calculates to runtime the number of used entries, free entries, total entries, 529 * and amount namespace in partition. 530 * 531 * \code{c} 532 * // Example of nvs_get_stats() to get the number of used entries and free entries: 533 * nvs_stats_t nvs_stats; 534 * nvs_get_stats(NULL, &nvs_stats); 535 * printf("Count: UsedEntries = (%d), FreeEntries = (%d), AllEntries = (%d)\n", 536 nvs_stats.used_entries, nvs_stats.free_entries, nvs_stats.total_entries); 537 * \endcode 538 * 539 * @param[in] part_name Partition name NVS in the partition table. 540 * If pass a NULL than will use NVS_DEFAULT_PART_NAME ("nvs"). 541 * 542 * @param[out] nvs_stats Returns filled structure nvs_states_t. 543 * It provides info about used memory the partition. 544 * 545 * 546 * @return 547 * - ESP_OK if the changes have been written successfully. 548 * Return param nvs_stats will be filled. 549 * - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "name" is not found. 550 * Return param nvs_stats will be filled 0. 551 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. 552 * Return param nvs_stats will be filled 0. 553 * - ESP_ERR_INVALID_ARG if nvs_stats equal to NULL. 554 * - ESP_ERR_INVALID_STATE if there is page with the status of INVALID. 555 * Return param nvs_stats will be filled not with correct values because 556 * not all pages will be counted. Counting will be interrupted at the first INVALID page. 557 */ 558 esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats); 559 560 /** 561 * @brief Calculate all entries in a namespace. 562 * 563 * An entry represents the smallest storage unit in NVS. 564 * Strings and blobs may occupy more than one entry. 565 * Note that to find out the total number of entries occupied by the namespace, 566 * add one to the returned value used_entries (if err is equal to ESP_OK). 567 * Because the name space entry takes one entry. 568 * 569 * \code{c} 570 * // Example of nvs_get_used_entry_count() to get amount of all key-value pairs in one namespace: 571 * nvs_handle_t handle; 572 * nvs_open("namespace1", NVS_READWRITE, &handle); 573 * ... 574 * size_t used_entries; 575 * size_t total_entries_namespace; 576 * if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){ 577 * // the total number of entries occupied by the namespace 578 * total_entries_namespace = used_entries + 1; 579 * } 580 * \endcode 581 * 582 * @param[in] handle Handle obtained from nvs_open function. 583 * 584 * @param[out] used_entries Returns amount of used entries from a namespace. 585 * 586 * 587 * @return 588 * - ESP_OK if the changes have been written successfully. 589 * Return param used_entries will be filled valid value. 590 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. 591 * Return param used_entries will be filled 0. 592 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL. 593 * Return param used_entries will be filled 0. 594 * - ESP_ERR_INVALID_ARG if used_entries equal to NULL. 595 * - Other error codes from the underlying storage driver. 596 * Return param used_entries will be filled 0. 597 */ 598 esp_err_t nvs_get_used_entry_count(nvs_handle_t handle, size_t* used_entries); 599 600 /** 601 * @brief Create an iterator to enumerate NVS entries based on one or more parameters 602 * 603 * \code{c} 604 * // Example of listing all the key-value pairs of any type under specified partition and namespace 605 * nvs_iterator_t it = nvs_entry_find(partition, namespace, NVS_TYPE_ANY); 606 * while (it != NULL) { 607 * nvs_entry_info_t info; 608 * nvs_entry_info(it, &info); 609 * it = nvs_entry_next(it); 610 * printf("key '%s', type '%d' \n", info.key, info.type); 611 * }; 612 * // Note: no need to release iterator obtained from nvs_entry_find function when 613 * // nvs_entry_find or nvs_entry_next function return NULL, indicating no other 614 * // element for specified criteria was found. 615 * } 616 * \endcode 617 * 618 * @param[in] part_name Partition name 619 * 620 * @param[in] namespace_name Set this value if looking for entries with 621 * a specific namespace. Pass NULL otherwise. 622 * 623 * @param[in] type One of nvs_type_t values. 624 * 625 * @return 626 * Iterator used to enumerate all the entries found, 627 * or NULL if no entry satisfying criteria was found. 628 * Iterator obtained through this function has to be released 629 * using nvs_release_iterator when not used any more. 630 */ 631 nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type); 632 633 /** 634 * @brief Returns next item matching the iterator criteria, NULL if no such item exists. 635 * 636 * Note that any copies of the iterator will be invalid after this call. 637 * 638 * @param[in] iterator Iterator obtained from nvs_entry_find function. Must be non-NULL. 639 * 640 * @return 641 * NULL if no entry was found, valid nvs_iterator_t otherwise. 642 */ 643 nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator); 644 645 /** 646 * @brief Fills nvs_entry_info_t structure with information about entry pointed to by the iterator. 647 * 648 * @param[in] iterator Iterator obtained from nvs_entry_find or nvs_entry_next function. Must be non-NULL. 649 * 650 * @param[out] out_info Structure to which entry information is copied. 651 */ 652 void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info); 653 654 /** 655 * @brief Release iterator 656 * 657 * @param[in] iterator Release iterator obtained from nvs_entry_find function. NULL argument is allowed. 658 * 659 */ 660 void nvs_release_iterator(nvs_iterator_t iterator); 661 662 663 #ifdef __cplusplus 664 } // extern "C" 665 #endif 666 667 #endif //ESP_NVS_H 668
