共用方式為

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。 可能的傳回值包括下列錯誤狀態代碼。

傳回碼 Description
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 開始提供。
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL

另請參閱

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING