共用方式為

GetFirmwareEnvironmentVariableExA 函式 (winbase.h)

  • 發行項

擷取指定韌體環境變數及其屬性的值。

語法

DWORD GetFirmwareEnvironmentVariableExA(
  LPCSTR lpName,
  LPCSTR lpGuid,
  PVOID  pBuffer,
  DWORD  nSize,
  PDWORD pdwAttribubutes
);

參數

lpName

韌體環境變數的名稱。 指標不得為 NULL。

lpGuid

GUID，表示韌體環境變數的命名空間。 GUID 必須是格式為 “{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxx}” 的字串串，其中 'x' 代表十六進位值。 指標不得為 NULL。

pBuffer

接收指定韌體環境變數值的緩衝區指標。

nSize

pValue 緩衝區的大小，以位元組為單位。

pdwAttribubutes

識別與變數相關聯的 UEFI 變數屬性的位掩碼。 如需位掩碼定義，請參閱 SetFirmwareEnvironmentVariableEx 。

傳回值

如果函式成功，傳回值就是 儲存在 pValue 緩衝區中的位元元組數目。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 可能的錯誤碼包括ERROR_INVALID_FUNCTION。

備註

從 Windows 10 1803 版開始，通用 Windows 應用程式可以讀取和寫入 UEFI 韌體變數。 如需詳細資訊，請參閱 從通用 Windows 應用程式存取 UEFI 韌體變數 。

若要讀取 UEFI 韌體環境變數，應用程式執行所在的使用者帳戶必須具有 SE_SYSTEM_ENVIRONMENT_NAME 許可權。 通用 Windows 應用程式必須從系統管理員帳戶執行，並遵循 從通用 Windows 應用程式存取 UEFI 韌體變數中所述的需求。

從 Windows 10 1803 版開始，從 User-Mode Driver Framework (UMDF) 驅動程式也支援讀取統一可擴展韌體介面 (UEFI) 變數。 不支援從 UMDF 驅動程式撰寫 UEFI 變數。

確切的韌體環境變數集是由開機韌體決定。 這些環境變數的位置也會由韌體指定。 例如，在以 UEFI 為基礎的系統上，NVRAM 包含指定系統開機設定的韌體環境變數。 如需所使用特定變數的相關信息，請參閱 UEFI 規格。 如需 UEFI 和 Windows 的詳細資訊，請參閱 UEFI 和 Windows。

舊版 BIOS 型系統上不支援韌體變數。 GetFirmwareEnvironmentVariableEx 函式一律會在舊版 BIOS 系統上失敗，或者 Windows 是在支援舊版 BIOS 和 UEFI 的系統上使用舊版 BIOS 安裝。 若要識別這些條件，請使用虛擬韌體環境名稱呼叫函式，例如 lpName 參數的空字串 (“”“) ，以及 lpGuid 參數的虛擬 GUID，例如 ”{00000000-0000-0000-0000-000000000000}“。 在舊版 BIOS 型系統上，或在支援舊版 BIOS 和 UEFI 的系統上，使用舊版 BIOS 安裝 Windows 時，函式將會失敗並ERROR_INVALID_FUNCTION。 在以 UEFI 為基礎的系統上，函式將會失敗，並出現韌體特定的錯誤，例如 ERROR_NOACCESS，表示虛擬 GUID 命名空間不存在。

如果您要建立備份應用程式，您可以使用此函式來儲存系統的所有開機設定，以便視需要使用 SetFirmwareEnvironmentVariable 函式 進行還原。

注意

winbase.h 標頭會根據 UNICODE 預處理器常數的定義，將 GetFirmwareEnvironmentVariableEx 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 Windows 8 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winbase.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

從通用 Windows 應用程式存取 UEFI 韌體變數

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx