GetFirmwareEnvironmentVariableA-Funktion (winbase.h)
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