通过

ExGetFirmwareEnvironmentVariable 函数 (wdm.h)

  • 项目

ExGetFirmwareEnvironmentVariable 例程获取指定的系统固件环境变量的值。

语法

NTSTATUS ExGetFirmwareEnvironmentVariable(
  [in]            PUNICODE_STRING VariableName,
  [in]            LPGUID          VendorGuid,
  [out, optional] PVOID           Value,
  [in, out]       PULONG          ValueLength,
  [out, optional] PULONG          Attributes
);

参数

[in] VariableName

指向包含指定环境变量名称 的 UNICODE_STRING 结构的指针。

[in] VendorGuid

指向 GUID 的指针，该 GUID 标识与指定环境变量关联的供应商。 环境变量根据其供应商 GUID 分组到命名空间中。 某些硬件平台可能不支持供应商 GUID。 在这些平台上，所有变量都分组到一个公共命名空间中，并忽略 VendorGuid 参数。

[out, optional] Value

指向调用方分配的缓冲区的指针，例程将指定环境变量的值写入该缓冲区。

[in, out] ValueLength

指向包含缓冲区大小的位置的指针。 输入时，此参数指向的位置包含调用方提供 的值 缓冲区的大小（以字节为单位）。 在退出之前，例程会将变量值的大小（以字节为单位）写入到此位置。 如果例程返回STATUS_SUCCESS，则 *ValueLength 输出值是写入到 Value 缓冲区的数据的字节数。 如果例程返回STATUS_BUFFER_TOO_SMALL，则 *ValueLength 是所需的缓冲区大小。

[out, optional] Attributes

指向例程将指定环境变量的属性写入到的位置的指针。 此参数是可选的，如果调用方不需要属性，则可以将其设置为 NULL。 有关详细信息，请参阅“备注”。

返回值

如果成功，ExGetFirmwareEnvironmentVariable 将返回STATUS_SUCCESS。 可能的返回值包括以下错误状态代码。

返回代码 说明
STATUS_INSUFFICIENT_RESOURCES 可用系统资源不足，无法完成请求的操作。
STATUS_BUFFER_TOO_SMALL 值缓冲区太小。
STATUS_VARIABLE_NOT_FOUND 请求的变量不存在。
STATUS_INVALID_PARAMETER 其中一个参数无效。
STATUS_NOT_IMPLEMENTED 此平台上不支持此例程。
STATUS_UNSUCCESSFUL 固件返回了无法识别的错误。

注解

系统固件环境变量包含硬件平台中实现的启动固件环境与操作系统加载程序以及固件环境中运行的其他软件之间传递的数据值。

硬件平台中可用的固件环境变量集取决于启动固件。 这些环境变量的位置也由固件指定。 例如，在基于 UEFI 的平台上，NVRAM 包含指定系统启动设置的固件环境变量。 有关使用的特定变量的信息，请参阅 UEFI 网站上的统一可扩展固件接口规范。 有关 UEFI 和 Windows 的详细信息，请参阅 UEFI 和 Windows。

基于 BIOS 的旧版平台上不支持固件环境变量。 在基于 BIOS 的旧平台上，对 ExGetFirmwareEnvironmentVariable 的 调用始终失败;如果在同时支持旧版 BIOS 和 UEFI 的平台上使用旧版 BIOS 安装 Windows，它们也会失败。 若要识别这些条件，请先使用 uuidgen 或类似工具来静态生成随机唯一 GUID。 然后调用此例程以查找特定的变量名称，并提供该 GUID 作为 VendorGuid 参数。

在基于 BIOS 的旧版平台上，或在同时支持旧版 BIOS 和 UEFI 但使用旧版 BIOS 安装 Windows 的平台上，函数将失败并STATUS_NOT_IMPLEMENTED。 在基于 UEFI 的平台上，函数将失败，并出现特定于固件的错误（例如STATUS_VARIABLE_NOT_FOUND），指示虚拟 GUID 命名空间不存在。

如果调用方指定非 NULL Attributes 参数，则例程会将指定系统固件环境变量的属性写入 Attributes 指向的位置。 UEFI 规范的版本 2.3.1 定义了固件环境变量的以下属性。

变量名称 值
EFI_VARIABLE_NON_VOLATILE 0x00000001
EFI_VARIABLE_BOOTSERVICE_ACCESS 0x00000002
EFI_VARIABLE_RUNTIME_ACCESS 0x00000004
EFI_VARIABLE_HARDWARE_ERROR_RECORD 0x00000008
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS 0x00000010
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS 0x00000020
EFI_VARIABLE_APPEND_WRITE 0x00000040

这些属性值定义为标志位。 写入由 Attributes 指向的 ULONG 变量的值为零或上表中一个或多个属性的按位 OR。 有关详细信息，请参阅 UEFI 网站上的 UEFI 规范。

如果创建备份数据存储，则可以使用此函数保存平台的所有启动设置，以便在需要时通过调用 ExSetFirmwareEnvironmentVariable 例程来还原这些设置。

ExGetFirmwareEnvironmentVariable 是 Win32 GetFirmwareEnvironmentVariable 函数的内核模式等效项。

要求

要求 值
最低受支持的客户端 从Windows 8开始可用。
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另请参阅

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING