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 aus einer universellen Windows-App .

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

Ab Windows 10 Version 1803 wird das Lesen von UEFI-Variablen (Unified Extensible Firmware Interface) auch von UMDF-Treibern (User-Mode Driver Framework) 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. 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 GetFirmwareEnvironmentVariableEx-Funktion schlägt immer auf einem BIOS-basierten Legacysystem fehl, oder wenn Windows mit 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.

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

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx