GetFirmwareEnvironmentVariableW-Funktion (winbase.h)

Artikel
11/20/2024

Ruft den Wert der angegebenen Firmwareumgebungsvariable ab.

Syntax

DWORD GetFirmwareEnvironmentVariableW(
  [in]  LPCWSTR lpName,
  [in]  LPCWSTR lpGuid,
  [out] PVOID   pBuffer,
  [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, wobei "x" einen Hexadezimalwert darstellt.

[out] pBuffer

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

[in] nSize

Die Größe des pBuffer- Puffers in Byte.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der im pBuffer 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 Unified Extensible Firmware Interface (UEFI)-Firmwarevariablen lesen und schreiben. Weitere Informationen finden Sie unter Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App-.

Um eine 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 GetFirmwareEnvironmentVariable-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.

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.

GetFirmwareEnvironmentVariable entspricht dem Benutzermodus der ExGetFirmwareEnvironmentVariable Kernelmodusroutine.

Anmerkung

Der winbase.h-Header definiert GetFirmwareEnvironmentVariable 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

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista, Windows XP mit SP1 [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll

Siehe auch

Zugreifen auf UEFI-Firmwarevariablen aus einer universellen Windows-App

GetFirmwareEnvironmentVariableEx-

SetFirmwareEnvironmentVariable

Systeminformationsfunktionen

Freigeben über