251 lines
12 KiB
C
251 lines
12 KiB
C
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
#ifndef ESP_NVS_H
|
|
#define ESP_NVS_H
|
|
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
#include <stdbool.h>
|
|
#include "esp_err.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* Opaque pointer type representing non-volatile storage handle
|
|
*/
|
|
typedef uint32_t nvs_handle;
|
|
|
|
#define ESP_ERR_NVS_BASE 0x1100
|
|
#define ESP_ERR_NVS_NOT_INITIALIZED (ESP_ERR_NVS_BASE + 0x01)
|
|
#define ESP_ERR_NVS_NOT_FOUND (ESP_ERR_NVS_BASE + 0x02)
|
|
#define ESP_ERR_NVS_TYPE_MISMATCH (ESP_ERR_NVS_BASE + 0x03)
|
|
#define ESP_ERR_NVS_READ_ONLY (ESP_ERR_NVS_BASE + 0x04)
|
|
#define ESP_ERR_NVS_NOT_ENOUGH_SPACE (ESP_ERR_NVS_BASE + 0x05)
|
|
#define ESP_ERR_NVS_INVALID_NAME (ESP_ERR_NVS_BASE + 0x06)
|
|
#define ESP_ERR_NVS_INVALID_HANDLE (ESP_ERR_NVS_BASE + 0x07)
|
|
#define ESP_ERR_NVS_REMOVE_FAILED (ESP_ERR_NVS_BASE + 0x08)
|
|
#define ESP_ERR_NVS_KEY_TOO_LONG (ESP_ERR_NVS_BASE + 0x09)
|
|
#define ESP_ERR_NVS_PAGE_FULL (ESP_ERR_NVS_BASE + 0x0a)
|
|
#define ESP_ERR_NVS_INVALID_STATE (ESP_ERR_NVS_BASE + 0x0b)
|
|
#define ESP_ERR_NVS_INVALID_LENGTH (ESP_ERR_NVS_BASE + 0x0c)
|
|
|
|
typedef enum {
|
|
NVS_READONLY,
|
|
NVS_READWRITE
|
|
} nvs_open_mode;
|
|
|
|
/**
|
|
* @brief Open non-volatile storage with a given namespace
|
|
*
|
|
* Multiple internal ESP-IDF and third party application modules can store
|
|
* their key-value pairs in the NVS module. In order to reduce possible
|
|
* conflicts on key names, each module can use its own namespace.
|
|
*
|
|
* @param[in] name Namespace name. Maximal length is determined by the
|
|
* underlying implementation, but is guaranteed to be
|
|
* at least 16 characters. Shouldn't be empty.
|
|
* @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
|
|
* open a handle for reading only. All write requests will
|
|
* be rejected for this handle.
|
|
* @param[out] out_handle If successful (return code is zero), handle will be
|
|
* returned in this argument.
|
|
*
|
|
* @return - ESP_OK if storage handle was opened successfully
|
|
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
|
|
* - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
|
|
* mode is NVS_READONLY
|
|
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
|
|
* - other error codes from the underlying storage driver
|
|
*/
|
|
esp_err_t nvs_open(const char* name, nvs_open_mode open_mode, nvs_handle *out_handle);
|
|
|
|
/**
|
|
* @brief nvs_set_X - set value for given key
|
|
*
|
|
* This family of functions set value for the key, given its name. Note that
|
|
* actual storage will not be updated until nvs_commit function is called.
|
|
*
|
|
* @param[in] handle Handle obtained from nvs_open function.
|
|
* Handles that were opened read only cannot be used.
|
|
* @param[in] key Key name. Maximal length is determined by the underlying
|
|
* implementation, but is guaranteed to be at least
|
|
* 16 characters. Shouldn't be empty.
|
|
* @param[in] value The value to set.
|
|
* @param[in] length For nvs_set_blob: length of binary value to set, in bytes.
|
|
*
|
|
* @return - ESP_OK if value was set successfully
|
|
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
|
|
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
|
|
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
|
|
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
|
|
* underlying storage to save the value
|
|
* - ESP_ERR_NVS_REMOVE_FAILED if 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.
|
|
*/
|
|
esp_err_t nvs_set_i8 (nvs_handle handle, const char* key, int8_t value);
|
|
esp_err_t nvs_set_u8 (nvs_handle handle, const char* key, uint8_t value);
|
|
esp_err_t nvs_set_i16 (nvs_handle handle, const char* key, int16_t value);
|
|
esp_err_t nvs_set_u16 (nvs_handle handle, const char* key, uint16_t value);
|
|
esp_err_t nvs_set_i32 (nvs_handle handle, const char* key, int32_t value);
|
|
esp_err_t nvs_set_u32 (nvs_handle handle, const char* key, uint32_t value);
|
|
esp_err_t nvs_set_i64 (nvs_handle handle, const char* key, int64_t value);
|
|
esp_err_t nvs_set_u64 (nvs_handle handle, const char* key, uint64_t value);
|
|
esp_err_t nvs_set_str (nvs_handle handle, const char* key, const char* value);
|
|
esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, size_t length);
|
|
|
|
/**
|
|
* @brief nvs_get_X - get value for given key
|
|
*
|
|
* These functions retrieve value for the key, given its name. 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.
|
|
* Additionally, nvs_get_str and nvs_get_blob 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.
|
|
*
|
|
* Example of using nvs_get_i32:
|
|
* int32_t max_buffer_size = 4096; // default value
|
|
* esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
|
|
* assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
|
|
* // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
|
|
* // have its default value.
|
|
*
|
|
* 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);
|
|
*
|
|
* @param[in] handle Handle obtained from nvs_open function.
|
|
* @param[in] key Key name. Maximal length is determined by the underlying
|
|
* implementation, but is guaranteed to be at least
|
|
* 16 characters. Shouldn't be empty.
|
|
* @param 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.
|
|
* @param[inout] length For nvs_get_str and nvs_get_blob, 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 - ESP_OK if the value was retrieved successfully
|
|
* - 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 length is not sufficient to store data
|
|
*/
|
|
esp_err_t nvs_get_i8 (nvs_handle handle, const char* key, int8_t* out_value);
|
|
esp_err_t nvs_get_u8 (nvs_handle handle, const char* key, uint8_t* out_value);
|
|
esp_err_t nvs_get_i16 (nvs_handle handle, const char* key, int16_t* out_value);
|
|
esp_err_t nvs_get_u16 (nvs_handle handle, const char* key, uint16_t* out_value);
|
|
esp_err_t nvs_get_i32 (nvs_handle handle, const char* key, int32_t* out_value);
|
|
esp_err_t nvs_get_u32 (nvs_handle handle, const char* key, uint32_t* out_value);
|
|
esp_err_t nvs_get_i64 (nvs_handle handle, const char* key, int64_t* out_value);
|
|
esp_err_t nvs_get_u64 (nvs_handle handle, const char* key, uint64_t* out_value);
|
|
esp_err_t nvs_get_str (nvs_handle handle, const char* key, char* out_value, size_t* length);
|
|
esp_err_t nvs_get_blob(nvs_handle handle, const char* key, void* out_value, size_t* length);
|
|
|
|
/**
|
|
* @brief Erase key-value pair with given key name.
|
|
*
|
|
* Note that actual storage may not be updated until nvs_commit function is called.
|
|
*
|
|
* @param[in] handle Storage handle obtained with nvs_open.
|
|
* Handles that were opened read only cannot be used.
|
|
*
|
|
* @param[in] key Key name. Maximal length is determined by the underlying
|
|
* implementation, but is guaranteed to be at least
|
|
* 16 characters. Shouldn't be empty.
|
|
*
|
|
* @return - ESP_OK if erase operation was successful
|
|
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
|
|
* - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
|
|
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
|
|
* - other error codes from the underlying storage driver
|
|
*/
|
|
esp_err_t nvs_erase_key(nvs_handle handle, const char* key);
|
|
|
|
/**
|
|
* @brief Erase all key-value pairs in a namespace
|
|
*
|
|
* Note that actual storage may not be updated until nvs_commit function is called.
|
|
*
|
|
* @param[in] handle Storage handle obtained with nvs_open.
|
|
* Handles that were opened read only cannot be used.
|
|
*
|
|
* @return - ESP_OK if erase operation was successful
|
|
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
|
|
* - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
|
|
* - other error codes from the underlying storage driver
|
|
*/
|
|
esp_err_t nvs_erase_all(nvs_handle handle);
|
|
|
|
/**
|
|
* @brief Write any pending changes to non-volatile storage
|
|
*
|
|
* After setting any values, nvs_commit() must be called to ensure changes are written
|
|
* to non-volatile storage. Individual implementations may write to storage at other times,
|
|
* but this is not guaranteed.
|
|
*
|
|
* @param[in] handle Storage handle obtained with nvs_open.
|
|
* Handles that were opened read only cannot be used.
|
|
*
|
|
* @return - ESP_OK if the changes have been written successfully
|
|
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
|
|
* - other error codes from the underlying storage driver
|
|
*/
|
|
esp_err_t nvs_commit(nvs_handle handle);
|
|
|
|
/**
|
|
* @brief Close the storage handle and free any allocated resources
|
|
*
|
|
* This function should be called for each handle opened with nvs_open once
|
|
* the handle is not in use any more. Closing the handle may not automatically
|
|
* write the changes to nonvolatile storage. This has to be done explicitly using
|
|
* nvs_commit function.
|
|
* Once this function is called on a handle, the handle should no longer be used.
|
|
*
|
|
* @param[in] handle Storage handle to close
|
|
*/
|
|
void nvs_close(nvs_handle handle);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif //ESP_NVS_H
|