SetFirmwareEnvironmentVariableExA-Funktion (winbase.h)
Legt den Wert der angegebenen Firmwareumgebungsvariablen 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 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. 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 Bytes. Wenn das VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS oder VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS Variablenattribut nicht über dwAttributes festgelegt wird, führt das Festlegen dieses Werts auf null zum Löschen dieser Variablen.
[in] dwAttributes
Bitmaske, um UEFI-Variablenattribute festzulegen, die der Variablen zugeordnet sind. Siehe auch UEFI-Spezifikation 2.3.1, Abschnitt 7.2.
| Wert | Bedeutung |
|---|---|
|
Die Firmwareumgebungsvariable wird im nicht flüchtigen Speicher (z. B. NVRAM) gespeichert. |
|
Auf die Firmwareumgebungsvariable kann während des Startdiensts zugegriffen werden. |
|
Auf die Firmwareumgebungsvariable kann zur Laufzeit zugegriffen werden.
Hinweis Für Variablen mit diesem Attributsatz muss ebenfalls VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS festgelegt sein.
|
|
Gibt hardwarebezogene Fehler an, die zur Laufzeit aufgetreten sind. |
|
Gibt eine Authentifizierungsanforderung an, die erfüllt werden muss, bevor in diese Firmwareumgebungsvariable geschrieben wird. Weitere Informationen finden Sie unter UEFI-Spezifikation 2.3.1. |
|
Gibt Authentifizierungs- und Zeitstempelanforderungen an, die vor dem Schreiben in diese Firmwareumgebungsvariable erfüllt werden müssen. Wenn dieses Attribut festgelegt ist, beginnt der durch pValue dargestellte Puffer mit einer instance 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 pValue an. 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 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 aus einer universellen Windows-App .
Ab Windows 10 Version 1803 wird das Lesen von UEFI-Firmwarevariablen auch von umdf-Treibern (User-Mode Driver Framework) 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-Firmwarevariablen aus einer universellen Windows-App beschriebenen Anforderungen erfüllen.
Die richtige Methode zum Ändern der Attribute einer Variablen besteht darin, die Variable zu löschen und mit anderen Attributen neu zu erstellen.
Der genaue Satz 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 auf einem BIOS-basierten Legacysystem nicht unterstützt. Die SetFirmwareEnvironmentVariableEx-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 auf, z. B. einer leeren Zeichenfolge ("") für den parameter lpName und einer Dummy-GUID wie "{00000000-0000-0000-0000-000000000000}" für den lpGuid-Parameter . Auf einem BIOS-älteren System oder auf einem System, das sowohl Legacy-BIOS als auch UEFI unterstützt, auf 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.
Hinweis
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
| Unterstützte Mindestversion (Client) | Windows 8 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (Windows.h einschließen) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Zugreifen auf UEFI-Firmwarevariablen über eine universelle Windows-App