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 Firmwareumgebungsvariable darstellt. Die GUID muss eine Zeichenfolge im Format "{xx-xxxx-xxxx-xxxx-xxxx-xxxx}" 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 Byte.

pdwAttribubutes

Bitmaske zur Identifizierung von UEFI-Variablenattributen, die der Variablen zugeordnet sind. Informationen zur Bitmaskendefinition finden Sie unter SetFirmwareEnvironmentVariableEx-.

Rückgabewert

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

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

Um eine UEFI-Firmwareumgebungsvariable zu lesen, 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.

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

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

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 SetFirmwareEnvironmentVariable-Funktion wiederhergestellt werden können.

Anforderungen

Siehe auch

Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx