SetFirmwareEnvironmentVariableExA-Funktion (winbase.h)
Legt den Wert der angegebenen Firmwareumgebungsvariable als Attribute fest, die angeben, wie diese Variable gespeichert und verwaltet wird.
Syntax
BOOL SetFirmwareEnvironmentVariableExA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
Parameter
[in] lpName
Der Name der Firmwareumgebungsvariable. Der Zeiger darf nicht NULL-sein.
[in] lpGuid
Die GUID, die den Namespace der Firmwareumgebungsvariable darstellt. Die GUID muss eine Zeichenfolge im Format "{xx-xxxx-xxxx-xxxx-xxxx-xxxx}" sein. Wenn das System GUID-basierte Namespaces nicht unterstützt, wird dieser Parameter ignoriert. Der Zeiger darf nicht NULL-sein.
[in] pValue
Ein Zeiger auf den neuen Wert für die Firmwareumgebungsvariable.
[in] nSize
Die Größe des pValue- Puffers in Byte. Es sei denn, die VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS oder VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS Variablenattribut wird über dwAttributesfestgelegt, führt das Festlegen dieses Werts auf Null zum Löschen dieser Variablen.
[in] dwAttributes
Bitmaske zum Festlegen von UEFI-Variablenattributen, die der Variablen zugeordnet sind. Siehe auch UEFI Spec 2.3.1, Section 7.2.
| Wert | Bedeutung |
|---|---|
|
Die Firmwareumgebungsvariable wird im nicht veränderlichen Speicher (z. B. NVRAM) gespeichert. |
|
Auf die Firmwareumgebungsvariable kann während des Startdiensts zugegriffen werden. |
|
Auf die Firmwareumgebungsvariable kann zur Laufzeit zugegriffen werden.
Note Variables with this attribute set, must also have VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS set.
|
|
Gibt an, dass hardwarebezogene Fehler zur Laufzeit aufgetreten sind. |
|
Gibt eine Authentifizierungsanforderung an, die erfüllt werden muss, bevor Sie in diese Firmwareumgebungsvariable schreiben. Weitere Informationen finden Sie unter UEFI-Spezifikation 2.3.1. |
|
Gibt die Anforderungen an die Authentifizierung und den Zeitstempel an, die erfüllt werden müssen, bevor sie in diese Firmwareumgebungsvariable schreiben. Wenn dieses Attribut festgelegt ist, beginnt der Puffer, dargestellt durch pValue, mit einer Instanz eines vollständigen (und serialisierten) EFI_VARIABLE_AUTHENTICATION_2 Deskriptors. Weitere Informationen finden Sie unter UEFI-Spezifikation 2.3.1. |
|
Fügen Sie eine vorhandene Umgebungsvariable mit dem Wert pValuean. Wenn die Firmware den Vorgang nicht unterstützt, gibt SetFirmwareEnvironmentVariableEx- ERROR_INVALID_FUNCTION zurück. |
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. Mögliche Fehlercodes sind ERROR_INVALID_FUNCTION.
Bemerkungen
Ab Windows 10, Version 1803, können universelle Windows-Apps UEFI-Firmwarevariablen lesen und schreiben. Weitere Informationen finden Sie unter Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App-.
Ab Windows 10, Version 1803, wird das Lesen von UEFI-Firmwarevariablen auch von User-Mode Driver Framework (UMDF)-Treibern 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 SE_SYSTEM_ENVIRONMENT_NAME Berechtigung verfügen. Eine universelle Windows-App muss von einem Administratorkonto ausgeführt werden und die Anforderungen erfüllen, die in Access UEFI-Firmwarevariablen aus einer universellen Windows-Appbeschrieben sind.
Die richtige Methode zum Ändern der Attribute einer Variablen besteht darin, die Variable zu löschen und mit verschiedenen Attributen neu zu erstellen.
Die genaue Gruppe von Firmwareumgebungsvariablen wird durch die Startfirmware bestimmt. Der Speicherort dieser Umgebungsvariablen wird auch von der Firmware angegeben. Beispielsweise enthält NVRAM auf einem UEFI-basierten System 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 für ein älteres BIOS-basiertes System nicht unterstützt. Die SetFirmwareEnvironmentVariableEx--Funktion schlägt immer bei einem älteren BIOS-basierten System fehl, oder wenn Windows unter Verwendung von Legacy-BIOS auf einem System installiert wurde, das sowohl ältere 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 parameter lpName und einer Dummy-GUID wie "{00000000-0000-0000-0000-000000000000}" für den parameter lpGuid auf. Bei einem älteren BIOS-basierten System oder auf einem System, das sowohl ältere BIOS- als auch UEFI-Versionen unterstützt, bei denen Windows mit legacy BIOS installiert wurde, schlägt die Funktion mit ERROR_INVALID_FUNCTION fehl. Auf einem UEFI-basierten System schlägt die Funktion mit einem Fehler fehl, der für die Firmware spezifisch ist, z. B. ERROR_NOACCESS, um anzugeben, dass der Dummy-GUID-Namespace nicht vorhanden ist.
Anmerkung
Der winbase.h-Header definiert SetFirmwareEnvironmentVariableEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, 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 |
|---|---|
| mindestens unterstützte Client- | Windows 8 [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winbase.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |
Siehe auch
Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App