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 value for given key 175 * 176 * This family of functions set value for the key, given its name. Note that 177 * actual storage will not be updated until nvs_commit function 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 * For strings, the maximum length (including null character) is 184 * 4000 bytes. 185 * 186 * @return 187 * - ESP_OK if value was set successfully 188 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 189 * - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only 190 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 191 * - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the 192 * underlying storage to save the value 193 * - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash 194 * write operation has failed. The value was written however, and 195 * update will be finished after re-initialization of nvs, provided that 196 * flash operation doesn't fail again. 197 * - ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long 198 */ 199 esp_err_t nvs_set_i8 (nvs_handle_t handle, const char* key, int8_t value); 200 esp_err_t nvs_set_u8 (nvs_handle_t handle, const char* key, uint8_t value); 201 esp_err_t nvs_set_i16 (nvs_handle_t handle, const char* key, int16_t value); 202 esp_err_t nvs_set_u16 (nvs_handle_t handle, const char* key, uint16_t value); 203 esp_err_t nvs_set_i32 (nvs_handle_t handle, const char* key, int32_t value); 204 esp_err_t nvs_set_u32 (nvs_handle_t handle, const char* key, uint32_t value); 205 esp_err_t nvs_set_i64 (nvs_handle_t handle, const char* key, int64_t value); 206 esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value); 207 esp_err_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value); 208 /**@}*/ 209 210 /** 211 * @brief set variable length binary value for given key 212 * 213 * This family of functions set value for the key, given its name. Note that 214 * actual storage will not be updated until nvs_commit function is called. 215 * 216 * @param[in] handle Handle obtained from nvs_open function. 217 * Handles that were opened read only cannot be used. 218 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 219 * @param[in] value The value to set. 220 * @param[in] length length of binary value to set, in bytes; Maximum length is 221 * 508000 bytes or (97.6% of the partition size - 4000) bytes 222 * whichever is lower. 223 * 224 * @return 225 * - ESP_OK if value was set successfully 226 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 227 * - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only 228 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 229 * - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the 230 * underlying storage to save the value 231 * - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash 232 * write operation has failed. The value was written however, and 233 * update will be finished after re-initialization of nvs, provided that 234 * flash operation doesn't fail again. 235 * - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long 236 */ 237 esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value, size_t length); 238 239 /**@{*/ 240 /** 241 * @brief get value for given key 242 * 243 * These functions retrieve value for the key, given its name. If key does not 244 * exist, or the requested variable type doesn't match the type which was used 245 * when setting a value, an error is returned. 246 * 247 * In case of any error, out_value is not modified. 248 * 249 * All functions expect out_value to be a pointer to an already allocated variable 250 * of the given type. 251 * 252 * \code{c} 253 * // Example of using nvs_get_i32: 254 * int32_t max_buffer_size = 4096; // default value 255 * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size); 256 * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND); 257 * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still 258 * // have its default value. 259 * 260 * \endcode 261 * 262 * @param[in] handle Handle obtained from nvs_open function. 263 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 264 * @param out_value Pointer to the output value. 265 * May be NULL for nvs_get_str and nvs_get_blob, in this 266 * case required length will be returned in length argument. 267 * 268 * @return 269 * - ESP_OK if the value was retrieved successfully 270 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 271 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 272 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 273 * - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data 274 */ 275 esp_err_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value); 276 esp_err_t nvs_get_u8 (nvs_handle_t handle, const char* key, uint8_t* out_value); 277 esp_err_t nvs_get_i16 (nvs_handle_t handle, const char* key, int16_t* out_value); 278 esp_err_t nvs_get_u16 (nvs_handle_t handle, const char* key, uint16_t* out_value); 279 esp_err_t nvs_get_i32 (nvs_handle_t handle, const char* key, int32_t* out_value); 280 esp_err_t nvs_get_u32 (nvs_handle_t handle, const char* key, uint32_t* out_value); 281 esp_err_t nvs_get_i64 (nvs_handle_t handle, const char* key, int64_t* out_value); 282 esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value); 283 /**@}*/ 284 285 /** 286 * @brief get value for given key 287 * 288 * These functions retrieve the data of an entry, given its key. If key does not 289 * exist, or the requested variable type doesn't match the type which was used 290 * when setting a value, an error is returned. 291 * 292 * In case of any error, out_value is not modified. 293 * 294 * All functions expect out_value to be a pointer to an already allocated variable 295 * of the given type. 296 * 297 * nvs_get_str and nvs_get_blob functions support WinAPI-style length queries. 298 * To get the size necessary to store the value, call nvs_get_str or nvs_get_blob 299 * with zero out_value and non-zero pointer to length. Variable pointed to 300 * by length argument will be set to the required length. For nvs_get_str, 301 * this length includes the zero terminator. When calling nvs_get_str and 302 * nvs_get_blob with non-zero out_value, length has to be non-zero and has to 303 * point to the length available in out_value. 304 * It is suggested that nvs_get/set_str is used for zero-terminated C strings, and 305 * nvs_get/set_blob used for arbitrary data structures. 306 * 307 * \code{c} 308 * // Example (without error checking) of using nvs_get_str to get a string into dynamic array: 309 * size_t required_size; 310 * nvs_get_str(my_handle, "server_name", NULL, &required_size); 311 * char* server_name = malloc(required_size); 312 * nvs_get_str(my_handle, "server_name", server_name, &required_size); 313 * 314 * // Example (without error checking) of using nvs_get_blob to get a binary data 315 * into a static array: 316 * uint8_t mac_addr[6]; 317 * size_t size = sizeof(mac_addr); 318 * nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size); 319 * \endcode 320 * 321 * @param[in] handle Handle obtained from nvs_open function. 322 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 323 * @param out_value Pointer to the output value. 324 * May be NULL for nvs_get_str and nvs_get_blob, in this 325 * case required length will be returned in length argument. 326 * @param[inout] length A non-zero pointer to the variable holding the length of out_value. 327 * In case out_value a zero, will be set to the length 328 * required to hold the value. In case out_value is not 329 * zero, will be set to the actual length of the value 330 * written. For nvs_get_str this includes zero terminator. 331 * 332 * @return 333 * - ESP_OK if the value was retrieved successfully 334 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 335 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 336 * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints 337 * - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data 338 */ 339 /**@{*/ 340 esp_err_t nvs_get_str (nvs_handle_t handle, const char* key, char* out_value, size_t* length); 341 esp_err_t nvs_get_blob(nvs_handle_t handle, const char* key, void* out_value, size_t* length); 342 /**@}*/ 343 344 /** 345 * @brief Erase key-value pair with given key name. 346 * 347 * Note that actual storage may not be updated until nvs_commit function is called. 348 * 349 * @param[in] handle Storage handle obtained with nvs_open. 350 * Handles that were opened read only cannot be used. 351 * 352 * @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty. 353 * 354 * @return 355 * - ESP_OK if erase operation was successful 356 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 357 * - ESP_ERR_NVS_READ_ONLY if handle was opened as read only 358 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist 359 * - other error codes from the underlying storage driver 360 */ 361 esp_err_t nvs_erase_key(nvs_handle_t handle, const char* key); 362 363 /** 364 * @brief Erase all key-value pairs in a namespace 365 * 366 * Note that actual storage may not be updated until nvs_commit function is called. 367 * 368 * @param[in] handle Storage handle obtained with nvs_open. 369 * Handles that were opened read only cannot be used. 370 * 371 * @return 372 * - ESP_OK if erase operation was successful 373 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 374 * - ESP_ERR_NVS_READ_ONLY if handle was opened as read only 375 * - other error codes from the underlying storage driver 376 */ 377 esp_err_t nvs_erase_all(nvs_handle_t handle); 378 379 /** 380 * @brief Write any pending changes to non-volatile storage 381 * 382 * After setting any values, nvs_commit() must be called to ensure changes are written 383 * to non-volatile storage. Individual implementations may write to storage at other times, 384 * but this is not guaranteed. 385 * 386 * @param[in] handle Storage handle obtained with nvs_open. 387 * Handles that were opened read only cannot be used. 388 * 389 * @return 390 * - ESP_OK if the changes have been written successfully 391 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL 392 * - other error codes from the underlying storage driver 393 */ 394 esp_err_t nvs_commit(nvs_handle_t handle); 395 396 /** 397 * @brief Close the storage handle and free any allocated resources 398 * 399 * This function should be called for each handle opened with nvs_open once 400 * the handle is not in use any more. Closing the handle may not automatically 401 * write the changes to nonvolatile storage. This has to be done explicitly using 402 * nvs_commit function. 403 * Once this function is called on a handle, the handle should no longer be used. 404 * 405 * @param[in] handle Storage handle to close 406 */ 407 void nvs_close(nvs_handle_t handle); 408 409 /** 410 * @note Info about storage space NVS. 411 */ 412 typedef struct { 413 size_t used_entries; /**< Amount of used entries. */ 414 size_t free_entries; /**< Amount of free entries. */ 415 size_t total_entries; /**< Amount all available entries. */ 416 size_t namespace_count; /**< Amount name space. */ 417 } nvs_stats_t; 418 419 /** 420 * @brief Fill structure nvs_stats_t. It provides info about used memory the partition. 421 * 422 * This function calculates to runtime the number of used entries, free entries, total entries, 423 * and amount namespace in partition. 424 * 425 * \code{c} 426 * // Example of nvs_get_stats() to get the number of used entries and free entries: 427 * nvs_stats_t nvs_stats; 428 * nvs_get_stats(NULL, &nvs_stats); 429 * printf("Count: UsedEntries = (%d), FreeEntries = (%d), AllEntries = (%d)\n", 430 nvs_stats.used_entries, nvs_stats.free_entries, nvs_stats.total_entries); 431 * \endcode 432 * 433 * @param[in] part_name Partition name NVS in the partition table. 434 * If pass a NULL than will use NVS_DEFAULT_PART_NAME ("nvs"). 435 * 436 * @param[out] nvs_stats Returns filled structure nvs_states_t. 437 * It provides info about used memory the partition. 438 * 439 * 440 * @return 441 * - ESP_OK if the changes have been written successfully. 442 * Return param nvs_stats will be filled. 443 * - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "name" is not found. 444 * Return param nvs_stats will be filled 0. 445 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. 446 * Return param nvs_stats will be filled 0. 447 * - ESP_ERR_INVALID_ARG if nvs_stats equal to NULL. 448 * - ESP_ERR_INVALID_STATE if there is page with the status of INVALID. 449 * Return param nvs_stats will be filled not with correct values because 450 * not all pages will be counted. Counting will be interrupted at the first INVALID page. 451 */ 452 esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats); 453 454 /** 455 * @brief Calculate all entries in a namespace. 456 * 457 * Note that to find out the total number of records occupied by the namespace, 458 * add one to the returned value used_entries (if err is equal to ESP_OK). 459 * Because the name space entry takes one entry. 460 * 461 * \code{c} 462 * // Example of nvs_get_used_entry_count() to get amount of all key-value pairs in one namespace: 463 * nvs_handle_t handle; 464 * nvs_open("namespace1", NVS_READWRITE, &handle); 465 * ... 466 * size_t used_entries; 467 * size_t total_entries_namespace; 468 * if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){ 469 * // the total number of records occupied by the namespace 470 * total_entries_namespace = used_entries + 1; 471 * } 472 * \endcode 473 * 474 * @param[in] handle Handle obtained from nvs_open function. 475 * 476 * @param[out] used_entries Returns amount of used entries from a namespace. 477 * 478 * 479 * @return 480 * - ESP_OK if the changes have been written successfully. 481 * Return param used_entries will be filled valid value. 482 * - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized. 483 * Return param used_entries will be filled 0. 484 * - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL. 485 * Return param used_entries will be filled 0. 486 * - ESP_ERR_INVALID_ARG if used_entries equal to NULL. 487 * - Other error codes from the underlying storage driver. 488 * Return param used_entries will be filled 0. 489 */ 490 esp_err_t nvs_get_used_entry_count(nvs_handle_t handle, size_t* used_entries); 491 492 /** 493 * @brief Create an iterator to enumerate NVS entries based on one or more parameters 494 * 495 * \code{c} 496 * // Example of listing all the key-value pairs of any type under specified partition and namespace 497 * nvs_iterator_t it = nvs_entry_find(partition, namespace, NVS_TYPE_ANY); 498 * while (it != NULL) { 499 * nvs_entry_info_t info; 500 * nvs_entry_info(it, &info); 501 * it = nvs_entry_next(it); 502 * printf("key '%s', type '%d' \n", info.key, info.type); 503 * }; 504 * // Note: no need to release iterator obtained from nvs_entry_find function when 505 * // nvs_entry_find or nvs_entry_next function return NULL, indicating no other 506 * // element for specified criteria was found. 507 * } 508 * \endcode 509 * 510 * @param[in] part_name Partition name 511 * 512 * @param[in] namespace_name Set this value if looking for entries with 513 * a specific namespace. Pass NULL otherwise. 514 * 515 * @param[in] type One of nvs_type_t values. 516 * 517 * @return 518 * Iterator used to enumerate all the entries found, 519 * or NULL if no entry satisfying criteria was found. 520 * Iterator obtained through this function has to be released 521 * using nvs_release_iterator when not used any more. 522 */ 523 nvs_iterator_t nvs_entry_find(const char *part_name, const char *namespace_name, nvs_type_t type); 524 525 /** 526 * @brief Returns next item matching the iterator criteria, NULL if no such item exists. 527 * 528 * Note that any copies of the iterator will be invalid after this call. 529 * 530 * @param[in] iterator Iterator obtained from nvs_entry_find function. Must be non-NULL. 531 * 532 * @return 533 * NULL if no entry was found, valid nvs_iterator_t otherwise. 534 */ 535 nvs_iterator_t nvs_entry_next(nvs_iterator_t iterator); 536 537 /** 538 * @brief Fills nvs_entry_info_t structure with information about entry pointed to by the iterator. 539 * 540 * @param[in] iterator Iterator obtained from nvs_entry_find or nvs_entry_next function. Must be non-NULL. 541 * 542 * @param[out] out_info Structure to which entry information is copied. 543 */ 544 void nvs_entry_info(nvs_iterator_t iterator, nvs_entry_info_t *out_info); 545 546 /** 547 * @brief Release iterator 548 * 549 * @param[in] iterator Release iterator obtained from nvs_entry_find function. NULL argument is allowed. 550 * 551 */ 552 void nvs_release_iterator(nvs_iterator_t iterator); 553 554 555 #ifdef __cplusplus 556 } // extern "C" 557 #endif 558 559 #endif //ESP_NVS_H 560
