ExGetFirmwareEnvironmentVariable-Funktion (wdm.h)
Die ExGetFirmwareEnvironmentVariable Routine ruft den Wert der angegebenen Systemfirmwareumgebungsvariable ab.
Syntax
NTSTATUS ExGetFirmwareEnvironmentVariable(
[in] PUNICODE_STRING VariableName,
[in] LPGUID VendorGuid,
[out, optional] PVOID Value,
[in, out] PULONG ValueLength,
[out, optional] PULONG Attributes
);
Parameter
[in] VariableName
Ein Zeiger auf eine UNICODE_STRING Struktur, die den Namen der angegebenen Umgebungsvariable enthält.
[in] VendorGuid
Ein Zeiger auf eine GUID, die den Anbieter identifiziert, der der angegebenen Umgebungsvariablen zugeordnet ist. Umgebungsvariablen werden basierend auf ihren Lieferanten-GUIDs in Namespaces gruppiert. Einige Hardwareplattformen unterstützen möglicherweise keine Hersteller-GUIDs. Auf diesen Plattformen werden alle Variablen in einem gemeinsamen Namespace gruppiert, und der VendorGuid Parameter wird ignoriert.
[out, optional] Value
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine den Wert der angegebenen Umgebungsvariable schreibt.
[in, out] ValueLength
Ein Zeiger auf eine Position, die die Puffergröße enthält. Bei der Eingabe enthält die Position, auf die dieser Parameter verweist, die Größe des vom Aufrufer bereitgestellten Wert- Puffers in Byte. Vor dem Beenden schreibt die Routine an diese Position die Größe des Variablenwerts in Byte. Wenn die Routine STATUS_SUCCESS zurückgibt, ist der Wert *ValueLength Ausgabewert die Anzahl von Bytes, die in den Wert Puffer geschrieben wurden. Wenn die Routine STATUS_BUFFER_TOO_SMALL zurückgibt, ist *ValueLength die erforderliche Puffergröße.
[out, optional] Attributes
Ein Zeiger auf eine Position, an die die Routine die Attribute der angegebenen Umgebungsvariable schreibt. Dieser Parameter ist optional und kann auf NULL festgelegt werden, wenn der Aufrufer die Attribute nicht benötigt. Weitere Informationen finden Sie in den Hinweisen.
Rückgabewert
ExGetFirmwareEnvironmentVariable gibt STATUS_SUCCESS zurück, wenn dies erfolgreich ist. Mögliche Rückgabewerte sind die folgenden Fehlerstatuscodes.
Rückgabecode | Beschreibung |
---|---|
STATUS_INSUFFICIENT_RESOURCES | Verfügbare Systemressourcen reichen nicht aus, um den angeforderten Vorgang abzuschließen. |
STATUS_BUFFER_TOO_SMALL | Der Wert Puffer ist zu klein. |
STATUS_VARIABLE_NOT_FOUND | Die angeforderte Variable ist nicht vorhanden. |
STATUS_INVALID_PARAMETER | Einer der Parameter ist ungültig. |
STATUS_NOT_IMPLEMENTED | Diese Routine wird auf dieser Plattform nicht unterstützt. |
STATUS_UNSUCCESSFUL | Die Firmware hat einen unbekannten Fehler zurückgegeben. |
Bemerkungen
System-Firmwareumgebungsvariablen enthalten Datenwerte, die zwischen der in der Hardwareplattform implementierten Startfirmwareumgebung und den Betriebssystemladeprogramme und anderer Software übergeben werden, die in der Firmwareumgebung ausgeführt werden.
Die Gruppe der Firmwareumgebungsvariablen, die in einer Hardwareplattform verfügbar sind, hängt von der Startfirmware ab. Der Speicherort dieser Umgebungsvariablen wird auch von der Firmware angegeben. Beispielsweise enthält NVRAM auf einer UEFI-basierten Plattform Firmwareumgebungsvariablen, die Systemstarteinstellungen angeben. Informationen zu bestimmten verwendeten Variablen finden Sie in der Unified Extensible Firmware Interface Specification auf der website UEFI. Weitere Informationen zu UEFI und Windows finden Sie unter UEFI und Windows.
Firmwareumgebungsvariablen werden auf einer älteren BIOS-basierten Plattform nicht unterstützt. Aufrufe an ExGetFirmwareEnvironmentVariable immer auf einer älteren BIOS-basierten Plattform fehlschlagen; sie schlagen auch fehl, wenn Windows mit dem Legacy-BIOS auf einer Plattform installiert wurde, die sowohl legacy-BIOS als auch UEFI unterstützt. Um diese Bedingungen zu identifizieren, verwenden Sie zuerst uuidgen oder ein ähnliches Tool, um eine zufällige eindeutige GUID statisch zu generieren. Rufen Sie dann diese Routine auf, um nach einem bestimmten Variablennamen zu suchen und diese GUID als VendorGuid Parameter anzugeben.
Auf einer älteren BIOS-basierten Plattform oder auf einer Plattform, die sowohl legacy-BIOS als auch UEFI unterstützt, aber in dem Windows mit dem Legacy-BIOS installiert wurde, schlägt die Funktion mit STATUS_NOT_IMPLEMENTED fehl. Auf einer UEFI-basierten Plattform schlägt die Funktion mit einem für die Firmware spezifischen Fehler wie STATUS_VARIABLE_NOT_FOUND fehl, um anzugeben, dass der Dummy-GUID-Namespace nicht vorhanden ist.
Wenn der Aufrufer eine nicht NULL-Attributes Parameter angibt, schreibt die Routine die Attribute der angegebenen Systemfirmwareumgebungsvariable an den Speicherort, auf den Attributesverweist. Version 2.3.1 der UEFI-Spezifikation definiert die folgenden Attribute für Firmwareumgebungsvariablen.
Variablenname | Wert |
---|---|
EFI_VARIABLE_NON_VOLATILE | 0x00000001 |
EFI_VARIABLE_BOOTSERVICE_ACCESS | 0x00000002 |
EFI_VARIABLE_RUNTIME_ACCESS | 0x00000004 |
EFI_VARIABLE_HARDWARE_ERROR_RECORD | 0x00000008 |
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS | 0x00000010 |
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | 0x00000020 |
EFI_VARIABLE_APPEND_WRITE | 0x00000040 |
Diese Attributwerte werden als Flagbits definiert. Der wert, der in die ULONG-Variable geschrieben wurde, auf die durch Attributes verweist, ist entweder null oder der bitweise OR eines oder mehrerer Attribute in der vorherigen Tabelle. Weitere Informationen finden Sie in der UEFI-Spezifikation auf der website UEFI.
Wenn Sie einen Sicherungsdatenspeicher erstellen, können Sie diese Funktion verwenden, um alle Starteinstellungen für die Plattform zu speichern, damit sie wiederhergestellt werden können, indem Sie bei Bedarf die ExSetFirmwareEnvironmentVariable Routine aufrufen.
ExGetFirmwareEnvironmentVariable ist das Kernelmodusäquivalent der Win32-GetFirmwareEnvironmentVariable-Funktion.
Anforderungen
Anforderung | Wert |
---|---|
mindestens unterstützte Client- | Verfügbar ab Windows 8. |
Zielplattform- | Universal |
Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
Library | NtosKrnl.lib |
DLL- | NtosKrnl.exe |
IRQL- | PASSIVE_LEVEL |
Siehe auch
ExSetFirmwareEnvironmentVariable