共用方式為

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

包含緩衝區大小之位置的指標。 在專案上，這個參數所指向的位置包含呼叫端提供 Value 緩衝區的大小，以位元組為單位。 結束之前，例程會寫入這個位置變數值的大小，以位元組為單位。 如果例程傳回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 安裝 Windows，它們也會失敗。 若要識別這些條件，請先使用 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