通过

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。 在这些平台上，所有变量都分组为一个公共命名空间，并忽略 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 的旧平台不支持固件环境变量。 调用 ExGetFirmwareEnvironmentVariable 始终在基于 BIOS 的旧平台上失败;如果在支持旧 BIOS 和 UEFI 的平台上安装了旧版 BIOS，则它们也会失败。 若要识别这些条件，请先使用 uuidgen 或类似的工具静态生成随机唯一 GUID。 然后调用此例程来查找特定的变量名称，并提供该 GUID 作为 VendorGuid 参数。

在基于旧版 BIOS 的平台上，或在支持旧版 BIOS 和 UEFI 但 Windows 使用旧版 BIOS 安装的平台上，该函数将失败并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）
库 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

另请参阅

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING