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