SetFirmwareEnvironmentVariableExA 函式 (winbase.h)
將指定韌體環境變數的值設定為屬性,指出此變數的儲存和維護方式。
語法
BOOL SetFirmwareEnvironmentVariableExA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
參數
[in] lpName
韌體環境變數的名稱。 指標不得為 Null。
[in] lpGuid
GUID,表示韌體環境變數的命名空間。 GUID 必須是格式為 「{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}」 的字串。 如果系統不支援 GUID 型命名空間,則會忽略此參數。 指標不得為 Null。
[in] pValue
韌體環境變數之新值的指標。
[in] nSize
pValue緩衝區的大小,以位元組為單位。 除非透過 dwAttributes設定VARIABLE_ATTRIBUTE_APPEND_WRITE、VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS或VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS變數屬性,否則將此值設定為零會導致刪除此變數。
[in] dwAttributes
位元遮罩可設定與變數相關聯的 UEFI 變數屬性。 另請參閱 UEFI 規格 2.3.1,第 7.2 節。
值 | 意義 |
---|---|
|
韌體環境變數會儲存在非揮發性記憶體 (,例如 NVRAM) 。 |
|
您可以在開機服務期間存取韌體環境變數。 |
|
韌體環境變數可以在執行時間存取。
注意 具有此屬性集的變數也必須設定 VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS 。
|
|
指出在執行時間發生硬體相關錯誤。 |
|
指出在寫入此韌體環境變數之前必須符合的驗證需求。 如需詳細資訊,請參閱 UEFI 規格 2.3.1。 |
|
指出寫入此韌體環境變數之前必須符合的驗證和時間戳記需求。 設定此屬性時, 由 pValue表示的緩衝區會以完整 (的實例開始,並序列化) EFI_VARIABLE_AUTHENTICATION_2 描述元。 如需詳細資訊,請參閱 UEFI 規格 2.3.1。 |
|
附加具有 pValue值的現有環境變數。 如果韌體不支援作業, 則 SetFirmwareEnvironmentVariableEx 會傳回ERROR_INVALID_FUNCTION。 |
傳回值
如果函式成功,則傳回值是非零值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。 可能的錯誤碼包括ERROR_INVALID_FUNCTION。
備註
從 Windows 10 1803 版開始,通用 Windows 應用程式可以讀取和寫入 UEFI 韌體變數。 如需詳細資訊,請參閱 從通用 Windows 應用程式存取 UEFI 韌體變數 。
從 Windows 10 1803 版開始,從 User-Mode Driver Framework (UMDF) 驅動程式也支援讀取 UEFI 韌體變數。 不支援從 UMDF 驅動程式撰寫 UEFI 韌體變數。
若要撰寫韌體環境變數,應用程式執行所在的使用者帳戶必須具有 SE_SYSTEM_ENVIRONMENT_NAME 許可權。 通用 Windows 應用程式必須從系統管理員帳戶執行,並遵循 從通用 Windows 應用程式存取 UEFI 韌體變數中所述的需求。
變更變數屬性的正確方法是刪除變數,並使用不同的屬性重新建立變數。
確切的韌體環境變數集是由開機韌體決定。 這些環境變數的位置也會由韌體指定。 例如,在以 UEFI 為基礎的系統上,NVRAM 包含指定系統開機設定的韌體環境變數。 如需所使用特定變數的相關資訊,請參閱 UEFI 規格。 如需 UEFI 和 Windows 的詳細資訊,請參閱 UEFI 和 Windows。
舊版 BIOS 型系統上不支援韌體變數。 SetFirmwareEnvironmentVariableEx函式一律會在舊版 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 命名空間不存在。
注意
winbase.h 標頭會根據 UNICODE 預處理器常數的定義,將 SetFirmwareEnvironmentVariableEx 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | winbase.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |