Freigeben über


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

GetFirmwareEnvironmentVariable

UNICODE_STRING