SetFirmwareEnvironmentVariableA-Funktion (winbase.h)

  • Artikel

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

SetFirmwareEnvironmentVariableEx

Systeminformationsfunktionen