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 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.

[in] pValue

Ein Zeiger auf den neuen Wert für die Firmwareumgebungsvariable.

[in] nSize

Die Größe des pBuffer- Puffers in Byte. Wenn dieser Parameter null ist, wird die Firmwareumgebungsvariable gelöscht.

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 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 SetFirmwareEnvironmentVariable-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.

SetFirmwareEnvironmentVariable entspricht dem Benutzermodus der ExSetFirmwareEnvironmentVariable Kernelmodusroutine.

Anforderungen

Siehe auch

Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Systeminformationsfunktionen