setFirmwareEnvironmentVariableExA 函数 (winbase.h)

  • 项目

将指定的固件环境变量的值设置为指示如何存储和维护此变量的属性。

语法

BOOL SetFirmwareEnvironmentVariableExA(
  [in] LPCSTR lpName,
  [in] LPCSTR lpGuid,
  [in] PVOID  pValue,
  [in] DWORD  nSize,
  [in] DWORD  dwAttributes
);

参数

[in] lpName

固件环境变量的名称。 指针不得为 NULL。

[in] lpGuid

表示固件环境变量的命名空间的 GUID。 GUID 必须是格式为“{xxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}”的字符串。 如果系统不支持基于 GUID 的命名空间，则忽略此参数。 指针不得为 NULL。

[in] pValue

指向固件环境变量的新值的指针。

[in] nSize

pValue 缓冲区的大小（以字节为单位）。 除非通过 dwAttributes 设置VARIABLE_ATTRIBUTE_APPEND_WRITE、VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS或VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS变量属性，否则将此值设置为零将导致删除此变量。

[in] dwAttributes

用于设置与变量关联的 UEFI 变量属性的位掩码。 另请参阅 UEFI 规范 2.3.1 第 7.2 节。

值 含义
VARIABLE_ATTRIBUTE_NON_VOLATILE
0x00000001
 固件环境变量存储在非易失性内存中， (例如 NVRAM) 。
VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS
0x00000002
 可以在启动服务期间访问固件环境变量。
VARIABLE_ATTRIBUTE_RUNTIME_ACCESS
0x00000004
 可以在运行时访问固件环境变量。
注意 设置了此属性的变量还必须具有 VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS 集。
 
VARIABLE_ATTRIBUTE_HARDWARE_ERROR_RECORD
0x00000008
 指示在运行时遇到的硬件相关错误。
VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS
0x00000010
 指示在写入此固件环境变量之前必须满足的身份验证要求。 有关详细信息，请参阅 UEFI 规范 2.3.1。
VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
0x00000020
 指示在写入此固件环境变量之前必须满足的身份验证和时间戳要求。 设置此属性后，由 pValue 表示的缓冲区将以完整 (的实例开头，并序列化) EFI_VARIABLE_AUTHENTICATION_2 描述符。 有关详细信息，请参阅 UEFI 规范 2.3.1。
VARIABLE_ATTRIBUTE_APPEND_WRITE
0x00000040
 追加值为 pValue 的现有环境变量。 如果固件不支持该操作，则 SetFirmwareEnvironmentVariableEx 将返回ERROR_INVALID_FUNCTION。

返回值

如果函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。 可能的错误代码包括ERROR_INVALID_FUNCTION。

注解

从 Windows 10 版本 1803 开始，通用 Windows 应用可以读取和写入 UEFI 固件变量。 有关详细信息 ，请参阅从通用 Windows 应用访问 UEFI 固件变量 。

从 Windows 10 版本 1803 开始，还支持从 User-Mode Driver Framework (UMDF) 驱动程序读取 UEFI 固件变量。 不支持从 UMDF 驱动程序编写 UEFI 固件变量。

若要编写固件环境变量，运行应用的用户帐户必须具有 SE_SYSTEM_ENVIRONMENT_NAME 权限。 通用 Windows 应用必须从管理员帐户运行，并遵循 从通用 Windows 应用访问 UEFI 固件变量中所述的要求。

更改变量属性的正确方法是删除变量并使用不同的属性重新创建它。

确切的固件环境变量集由启动固件确定。 这些环境变量的位置也由固件指定。 例如，在基于 UEFI 的系统上，NVRAM 包含指定系统启动设置的固件环境变量。 有关使用的特定变量的信息，请参阅 UEFI 规范。 有关 UEFI 和 Windows 的详细信息，请参阅 UEFI 和 Windows。

基于 BIOS 的旧系统不支持固件变量。 SetFirmwareEnvironmentVariableEx 函数在基于 BIOS 的旧版系统上始终失败，或者如果在同时支持旧版 BIOS 和 UEFI 的系统上使用旧版 BIOS 安装 Windows， 若要识别这些条件，请使用虚拟固件环境名称（例如 lpName 参数的空字符串 (“”) ）和虚拟 GUID（如 lpGuid 参数的“”{00000000-0000-0000-0000-000000000000}）调用函数。 在基于 BIOS 的旧版系统上，或在同时支持旧版 BIOS 和 UEFI 的系统上（其中 Windows 是使用旧版 BIOS 安装的），函数将失败并ERROR_INVALID_FUNCTION。 在基于 UEFI 的系统上，函数将失败，并显示特定于固件的错误（例如ERROR_NOACCESS），指示虚拟 GUID 命名空间不存在。

注意

winbase.h 标头将 SetFirmwareEnvironmentVariableEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

   
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

从通用 Windows 应用访问 UEFI 固件变量

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable