GetFirmwareEnvironmentVariableA-Funktion (winbase.h)

  • Artikel

Ruft den Wert der angegebenen Firmwareumgebungsvariable ab.

Syntax

DWORD GetFirmwareEnvironmentVariableA(
  [in]  LPCSTR lpName,
  [in]  LPCSTR 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 Firmwareumgebungsvariablen darstellt. Die GUID muss eine Zeichenfolge im Format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" 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 Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl von Bytes, die im pBuffer-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 (Unified Extensible Firmware Interface) 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 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 GetFirmwareEnvironmentVariable-Funktion schlägt immer auf einem BIOS-basierten Legacysystem 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 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.

GetFirmwareEnvironmentVariable ist das Benutzermodusäquivalent der Kernelmodusroutine ExGetFirmwareEnvironmentVariable .

Hinweis

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

   
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 (Windows.h einschließen)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

Zugreifen auf UEFI-Firmwarevariablen über eine universelle Windows-App

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Systeminformationsfunktionen