Preferences 偏好

API

专题

ESP32

它使用 ESP32 的一部分板载非易失性存储器（NVS）来存储数据。此数据在系统重启和断电事件中保留。

Preferences （首选项）最适合存储许多小值，而不是几个大值。如果要存储大量数据，请考虑使用 LitteFS 等文件系统库。

Preferences 库可供所有 ESP32 变体使用。

头文件

#include <Preferences.h>

概述

库方法可用于：

创建命名空间;
打开和关闭命名空间;
在命名空间中存储和检索支持的数据类型的数据;
确定键值是否已初始化;
删除键值对;
删除命名空间中的所有键值对;
确定针对键存储的数据类型;
确定命名空间中的键条目数。

首选项直接支持以下数据类型：

表 1 — 首选项数据类型

首选项类型	数据类型	大小（字节）
Bool	bool	1
Char	int8_t	1
UChar	uint8_t	1
Short	int16_t	2
UShort	uint16_t	2
Int	int32_t	4
UInt	uint32_t	4
Long	int32_t	4
ULong	uint32_t	4
Float	float_t	4
Long64	int64_t	8
ULong64	uint64_t	8
Double	double_t	8
String	const char*	variable
String	String	variable
Bytes	uint8_t	variable

字符串值可以作为 Arduino String 或以 null 结尾的 char 数组（c-string）进行存储和检索。

Bytes 类型用于在命名空间中存储和检索任意数量的字节。

Arduino-esp32 首选项 API

begin 开始

从 NVS 分区中打开具有给定命名空间名称的非易失性存储器。
bool begin(const char * name, bool readOnly=false, const char* partition_label=NULL)
Parameters  参数

name （必需）

命名空间名称。最大长度为 15 个字符。

readOnly （可选）

false 将以读写模式打开命名空间。

true 将以只读模式打开命名空间。

如果省略，则以读写模式打开命名空间。

partition_label （可选）

要在其中打开命名空间的 NVS 分区的名称。

如果省略，则命名空间将在 “nvs” 分区中打开。

Returns  返回

true，表示命名空间打开成功;否则为 false。

Notes  笔记

如果分区中不存在命名空间，则首先创建该命名空间。

尝试将键值写入以只读模式打开的命名空间将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

end 结束

关闭当前打开的命名空间。
void end()
Parameters  参数

None  没有

Returns  返回

Nothing  无

Note  注意

关闭命名空间后，用于访问它的方法将失败。

clear 清楚

从当前打开的命名空间中删除所有键和值。
bool clear()
Parameters  参数

None  没有

Returns  返回

如果删除了所有键和值，则为 true;否则为 false。

Note  注意

之后，命名空间名称仍然存在。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

remove 删除

从当前打开的命名空间中删除键值对。
bool remove(const char * key)
Parameters  参数

key （必需）

需要删除的 Key 的名称。

Returns  返回

如果删除了键值对，则为 true;否则为 false。

Note  注意

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

isKey

检查当前打开的命名空间中是否存在键值对。
bool isKey(const char * key)
Parameters  参数

key （必需）

要检查的键的名称。

Returns  返回

如果存在键值对，则为 true;否则为 false。

Note  注意

尝试在命名空间未打开的情况下检查键将返回 false。

putChar, putUChar

在当前打开的命名空间中存储针对给定键的值。
size_t putChar(const char* key, int8_t value)
size_t putUChar(const char* key, uint8_t value)
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

必须与方法的数据类型匹配。

Returns  返回

如果调用成功，则为 1 （为这些数据类型存储的字节数）;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putShort, putUShort

在当前打开的命名空间中存储针对给定键的值。
size_t putShort(const char* key, int16_t value)
size_t putUShort(const char* key, uint16_t value)
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

必须与方法的数据类型匹配。

Returns  返回

2 （为这些数据类型存储的字节数）如果调用成功;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putInt, putUInt

putLong, putULong

putFloat

在当前打开的命名空间中存储针对给定键的值。
size_t putInt(const char* key, int32_t value)
size_t putUInt(const char* key, uint32_t value)
size_t putLong(const char* key, int32_t value)
size_t putULong(const char* key, uint32_t value)
size_t putFloat(const char* key, float_t value)
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

必须与方法的数据类型匹配。

Returns  返回

4 （为这些数据类型存储的字节数）如果调用成功;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putLong64, putULong64

putDouble

在当前打开的命名空间中存储针对给定键的值。
size_t putLong64(const char* key, int64_t value)
size_t putULong64(const char* key, uint64_t value)
size_t putDouble(const char* key, double_t value)
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

必须与方法的数据类型匹配。

Returns  返回

如果调用成功，则为 8 （为这些数据类型存储的字节数）;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putBool

在当前打开的命名空间中存储针对给定键的值。
size_t putBool(const char* key, bool value)
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

必须与方法的数据类型匹配。

Returns  返回

如果成功，则为 true;否则为 false。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putString

在当前打开的命名空间中存储针对给定键的可变长度值。
size_t putString(const char* key, const char* value);
size_t putString(const char* key, String value);
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

如果 const char*，则为以 null 结尾的（C 字符串）字符数组。

如果为 String，则为有效的 Arduino String 类型。

Returns  返回

如果成功：存储的字节数;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

putBytes

在当前打开的命名空间中针对给定键存储可变数量的字节。
size_t putBytes(const char* key, const void* value, size_t len);
Parameters  参数

key （必需）

如果 key 在当前打开的命名空间中不存在，则首先创建该 key。

value （必需）

指向包含要存储的字节的数组或缓冲区的指针。

len （必需）

要存储的 value 的字节数。

Returns  返回

如果成功：存储的字节数;否则为 0。

Notes  笔记

尝试在未以读写模式打开命名空间的情况下存储值将失败。

此方法对基础数据类型使用的字节进行作，而不是对给定数据类型的元素数进行作。之后，Preferences 库不会保留 value 的数据类型。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

getChar, getUChar

检索针对当前打开的命名空间中的给定键存储的值。
int8_t getChar(const char* key, int8_t defaultValue = 0)
uint8_t getUChar(const char* key, uint8_t defaultValue = 0)
Parameters  参数

key （必需）

defaultValue（可选）

必须与方法的数据类型匹配（如果提供）。

Returns  返回

the value stored against key if the call is successful.
如果调用成功，则针对 key 存储的值。

defaultValue, if it is provided; 0 otherwise.
defaultValue（如果提供）;否则为 0。

Notes  笔记

在没有命名空间可用的情况下尝试检索密钥将失败。

尝试从不存在的键中检索值将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

getShort, getUShort

检索针对当前打开的命名空间中的给定键存储的值。
int16_t getShort(const char* key, int16_t defaultValue = 0)
uint16_t getUShort(const char* key, uint16_t defaultValue = 0)
Except for the data type returned, behaves exactly like getChar.
除了返回的数据类型外，其行为与 getChar 完全相同。

getInt, getUInt getInt， getUInt

Retrieve a value stored against a given key in the currently open namespace.
检索针对当前打开的命名空间中的给定键存储的值。
int32_t getInt(const char* key, int32_t defaultValue = 0)
uint32_t getUInt(const char* key, uint32_t defaultValue = 0)
除了返回的数据类型外，其行为与 getChar 完全相同。

getLong, getULong

检索针对当前打开的命名空间中的给定键存储的值。
int32_t getLong(const char* key, int32_t defaultValue = 0)
uint32_t getULong(const char* key, uint32_t defaultValue = 0)
除了返回的数据类型外，其行为与 getChar 完全相同。

getLong64, getULong64

检索针对当前打开的命名空间中的给定键存储的值。
int64_t getLong64(const char* key, int64_t defaultValue = 0)
uint64_t getULong64(const char* key, uint64_t defaultValue = 0)
除了返回的数据类型外，其行为与 getChar 完全相同。

getFloat

检索针对当前打开的命名空间中的给定键存储的值。
float_t getFloat(const char* key, float_t defaultValue = NAN)
除了返回的数据类型和 defaultValue 的值外，其行为与 getChar 完全相同。

getDouble

检索针对当前打开的命名空间中的给定键存储的值。
double_t getDouble(const char* key, double_t defaultValue = NAN)
除了返回的数据类型和 defaultValue 的值外，其行为与 getChar 完全相同。

getBool

检索针对当前打开的命名空间中的给定键存储的值。
bool getBool(const char* key, bool defaultValue = false);
除了返回的数据类型外，其行为与 getChar 完全相同。

getString

将针对当前打开的命名空间中的给定键存储的 char 字符串复制到缓冲区。

size_t getString(const char* key, char* value, size_t len);

Parameters  参数

key （必需）

value （必需）

大小足以容纳 len 字节的缓冲区

len （必需）

要写入 value 指向的缓冲区的类型 char' 的数量

Returns  返回

如果成功;等于 len 的字节数将写入 value 指向的缓冲区，该方法返回 1。

如果方法失败，则不会将任何内容写入 value 指向的缓冲区，并且该方法返回 0。

Notes  笔记

len 必须等于针对 key 存储的字节数，否则调用将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

getString

检索针对当前打开的命名空间中的给定键存储的 Arduino String 值。

String getString(const char* key, String defaultValue = String());

Parameters  参数

key （必需）

defaultValue（可选）

Returns  返回

如果调用成功，则针对 key 存储的值

如果方法失败：如果提供，则返回 defaultValue;否则为 “”（空 String）。

Notes  笔记

defaultValue 的类型必须为 String。

getBytes

将针对当前打开的命名空间中的给定键存储的一系列字节复制到缓冲区。

size_t getBytes(const char* key, void * buf, size_t len);

Parameters  参数

key （必需）

buf （必需）

大小足以容纳 len 字节的缓冲区。

len （必需）

要写入 buf 指向的缓冲区的字节数

Returns  返回

如果成功，则等于 len 的字节数将写入缓冲区 buf，该方法返回 len。

如果方法失败，则不会向缓冲区写入任何内容，并且该方法返回 0。

Notes  笔记

len 必须等于针对 key 存储的字节数，否则调用将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

getBytesLength

根据当前打开的命名空间中 Bytes 类型的键获取值中存储的字节数。

size_t getBytesLength(const char* key)

Parameters  参数

key （必需）

Returns  返回

如果成功：针对 key 存储的值中的字节数;否则为 0。

Notes  笔记

如果 key 不是 Bytes 类型，该方法将失败。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

getType

获取当前打开的命名空间中给定键的 Preferences 数据类型。

PreferenceType getType(const char* key)

Parameters  参数

key （必需）

Returns  返回

一个 int 值，如下表 2 所示。

如果调用失败，则值为 10 （PT_INVALID）。

Notes  笔记

返回值在 Preferences.h 中枚举。表 2 包括列举的值以供参考。

返回值可以映射到多个 Prefs 类型。

如果出现以下情况，该方法将失败：命名空间未打开;密钥不存在;提供的密钥超过 15 个字符。

表 2 — getType 返回值

返回值	首选项类型	数据类型	枚举值
0	Char	int8_t	PT_I8
1	UChar	uint8_t	PT_U8
1	Bool	bool	PT_U8
2	Short	int16_t	PT_I16
3	UShort	uint16_t	PT_U16
4	Int	int32_t	PT_I32
4	Long	int32_t	PT_I32
5	UInt	uint32_t	PT_U32
5	ULong	uint32_t	PT_U32
6	Long64	int64_t	PT_I64
7	ULong64	uint64_t	PT_U64
8	String	String	PT_STR
8	String	*char	PT_STR
9	Double	double_t	PT_BLOB
	Float	float_t
	Bytes	uint8_t
10	-	-	PT_INVALID

freeEntries

获取当前打开的命名空间的键表中可用的空闲条目数。

size_t freeEntries()

Parameters  参数

none  没有

Returns  返回

如果成功：当前打开的命名空间的 key 表中可用的空闲条目数;否则为 0。

Notes  笔记

存储 Bool、Char、UChar、Short、UShort、Int、UInt、Long、ULong、Long64、ULong64 类型的值的键使用键表中的一个条目。

存储 Float 和 Double 类型的值的 keys 使用 key 表中的三个条目。

Arduino 或 c-string String 类型至少使用两个键表条目，条目数随着字符串长度的增加而增加。

存储 Bytes 类型值的键至少使用三个键表条目，条目数随着存储的字节数而增加。

将向 arduino-esp32 log_e 工具发送一条消息，说明呼叫失败的原因。

Arduino ESP32 指南

Preferences 偏好

头文件

概述

Arduino-esp32 首选项 API

begin 开始

end 结束

clear 清楚

remove 删除

isKey

putChar, putUChar

putShort, putUShort

putInt, putUInt

putLong, putULong

putFloat

putLong64, putULong64

putDouble

putBool

putString

putBytes

getChar, getUChar

getShort, getUShort

getInt, getUInt getInt， getUInt

getLong, getULong

getLong64, getULong64

getFloat

getDouble

getBool

getString

getString

getBytes

getBytesLength

getType

freeEntries