GetFirmwareEnvironmentVariableExA-Funktion (winbase.h)

Ruft den Wert der angegebenen Firmwareumgebungsvariable und deren Attribute ab.

Syntax

DWORD GetFirmwareEnvironmentVariableExA(
  LPCSTR lpName,
  LPCSTR lpGuid,
  PVOID  pBuffer,
  DWORD  nSize,
  PDWORD pdwAttribubutes
);

Parameter

lpName

Der Name der Firmwareumgebungsvariable. Der Zeiger darf nicht NULL sein.

lpGuid

Die GUID, die den Namespace der Firmwareumgebungsvariablen darstellt. Die GUID muss eine Zeichenfolge im Format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" sein, wobei "x" einen Hexadezimalwert darstellt. Der Zeiger darf nicht NULL sein.

pBuffer

Ein Zeiger auf einen Puffer, der den Wert der angegebenen Firmwareumgebungsvariable empfängt.

nSize

Die Größe des pValue-Puffers in Bytes.

pdwAttribubutes

Bitmaske, die UEFI-Variablenattribute identifiziert, die der Variablen zugeordnet sind. Die Bitmaskendefinition finden Sie unter SetFirmwareEnvironmentVariableEx .

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl von Bytes, die im pValue-Puffer gespeichert sind.

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 .

Zum Lesen einer UEFI-Firmwareumgebungsvariable 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.

Ab Windows 10 Version 1803 wird das Lesen von UEFI-Variablen (Unified Extensible Firmware Interface) auch von User-Mode Driver Framework-Treibern (UMDF) unterstützt. Das Schreiben von UEFI-Variablen aus UMDF-Treibern wird nicht unterstützt.

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

Wenn Sie eine Sicherungsanwendung erstellen, können Sie diese Funktion verwenden, um alle Starteinstellungen für das System zu speichern, damit sie bei Bedarf mithilfe der Funktion SetFirmwareEnvironmentVariable wiederhergestellt werden können.

Hinweis

Der winbase.h-Header definiert GetFirmwareEnvironmentVariableEx 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 8 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [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