SetFirmwareEnvironmentVariableA-Funktion (winbase.h)
Legt den Wert der angegebenen Firmwareumgebungsvariable fest.
Syntax
BOOL SetFirmwareEnvironmentVariableA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize
);
Parameter
[in] lpName
Der Name der Firmwareumgebungsvariable. Der Zeiger darf nicht NULL sein.
[in] lpGuid
Die GUID, die den Namespace der Firmwareumgebungsvariablen darstellt. Die GUID muss eine Zeichenfolge im Format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" sein. Wenn das System keine GUID-basierten Namespaces unterstützt, wird dieser Parameter ignoriert.
[in] pValue
Ein Zeiger auf den neuen Wert für die Firmwareumgebungsvariable.
[in] nSize
Die Größe des pBuffer-Puffers in Bytes. Wenn dieser Parameter 0 ist, wird die Firmwareumgebungsvariable gelöscht.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Mögliche Fehlercodes sind ERROR_INVALID_FUNCTION.
Hinweise
Ab Windows 10 Version 1803 können universelle Windows-Apps UEFI-Firmwarevariablen lesen und schreiben. Weitere Informationen finden Sie unter Zugreifen auf UEFI-Firmwarevariablen über eine universelle Windows-App .
Ab Windows 10, Version 1803, wird das Lesen von UEFI-Firmwarevariablen auch von User-Mode Driver Framework -Treibern (UMDF) unterstützt. Das Schreiben von UEFI-Firmwarevariablen aus UMDF-Treibern wird nicht unterstützt.
Um eine Firmwareumgebungsvariable zu schreiben, muss das Benutzerkonto, unter dem die App ausgeführt wird, über die berechtigung SE_SYSTEM_ENVIRONMENT_NAME verfügen. Eine universelle Windows-App muss über ein Administratorkonto ausgeführt werden und die unter Access UEFI firmware variables from a Universal Windows App beschriebenen Anforderungen erfüllen.
Der genaue Satz von Firmwareumgebungsvariablen wird durch die Startfirmware bestimmt. Der Speicherort dieser Umgebungsvariablen wird auch von der Firmware angegeben. Auf einem UEFI-basierten System enthält NVRAM beispielsweise Firmwareumgebungsvariablen, die Systemstarteinstellungen angeben. Informationen zu bestimmten verwendeten Variablen finden Sie in der UEFI-Spezifikation. Weitere Informationen zu UEFI und Windows finden Sie unter UEFI und Windows.
Firmwarevariablen werden in einem älteren BIOS-basierten System nicht unterstützt. Die SetFirmwareEnvironmentVariable-Funktion schlägt immer auf einem älteren BIOS-basierten System fehl, oder wenn Windows mithilfe des Legacy-BIOS auf einem System installiert wurde, das sowohl legacy BIOS als auch UEFI unterstützt. Um diese Bedingungen zu identifizieren, rufen Sie die Funktion mit einem Dummy-Firmwareumgebungsnamen wie einer leeren Zeichenfolge ("") für den lpName-Parameter und einer Dummy-GUID wie "{00000000-0000-0000-0000-000000000000}" für den lpGuid-Parameter auf. Auf einem Legacy-BIOS-basierten System oder auf einem System, das sowohl Legacy-BIOS als auch UEFI unterstützt, bei dem Windows mithilfe des Legacy-BIOS installiert wurde, schlägt die Funktion mit ERROR_INVALID_FUNCTION fehl. Auf einem UEFI-basierten System schlägt die Funktion mit einem firmwarespezifischen Fehler wie ERROR_NOACCESS fehl, um anzugeben, dass der Dummy-GUID-Namespace nicht vorhanden ist.
SetFirmwareEnvironmentVariable ist das Benutzermodusäquivalent der Kernelmodusroutine ExSetFirmwareEnvironmentVariable .
Hinweis
Der winbase.h-Header definiert SetFirmwareEnvironmentVariable als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP1 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (einschließlich Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Zugreifen auf UEFI-Firmwarevariablen über eine universelle Windows-App
GetFirmwareEnvironmentVariable