ExGetFirmwareEnvironmentVariable-Funktion (wdm.h)
Die ExGetFirmwareEnvironmentVariable-Routine ruft den Wert der angegebenen Umgebungsvariable der Systemfirmware 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 Umgebungsvariablen enthält.
[in] VendorGuid
Ein Zeiger auf eine GUID, die den Anbieter identifiziert, der der angegebenen Umgebungsvariablen zugeordnet ist. Umgebungsvariablen werden basierend auf ihren Anbieter-GUIDs in Namespaces gruppiert. Einige Hardwareplattformen unterstützen möglicherweise keine Anbieter-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. Beim Eintrag enthält der Speicherort, auf den dieser Parameter verweist, die Größe des vom Aufrufer bereitgestellten Wertpuffers in Bytes. Vor dem Beenden schreibt die Routine die Größe des Variablenwerts in Bytes an diesen Speicherort. Wenn die Routine STATUS_SUCCESS zurückgibt, ist der *ValueLength-Ausgabewert die Anzahl der Bytes von Daten, die in den Wertpuffer geschrieben wurden. Wenn die Routine STATUS_BUFFER_TOO_SMALL zurückgibt, ist *ValueLength die erforderliche Puffergröße.
[out, optional] Attributes
Ein Zeiger auf einen Speicherort, an den 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 bei erfolgreicher Ausführung STATUS_SUCCESS zurück. Mögliche Rückgabewerte sind der folgende Fehler status Codes.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Die verfügbaren Systemressourcen reichen nicht aus, um den angeforderten Vorgang abzuschließen. |
| STATUS_BUFFER_TOO_SMALL | Der Wertpuffer 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 nicht erkannten Fehler zurückgegeben. |
Hinweise
Umgebungsvariablen der Systemfirmware enthalten Datenwerte, die zwischen der auf der Hardwareplattform implementierten Startfirmwareumgebung und den Betriebssystemladeprogrammen und anderer Software übergeben werden, die in der Firmwareumgebung ausgeführt wird.
Welche Firmwareumgebungsvariablen auf einer Hardwareplattform verfügbar sind, hängt von der Startfirmware ab. Der Speicherort dieser Umgebungsvariablen wird auch von der Firmware angegeben. Auf einer UEFI-basierten Plattform enthält NVRAM beispielsweise Firmwareumgebungsvariablen, die Systemstarteinstellungen angeben. Informationen zu bestimmten verwendeten Variablen finden Sie unter Unified Extensible Firmware Interface Specification (Unified Extensible Firmware Interface Specification) auf der UEFI-Website . Weitere Informationen zu UEFI und Windows finden Sie unter UEFI und Windows.
Firmwareumgebungsvariablen werden auf einer älteren BIOS-basierten Plattform nicht unterstützt. Aufrufe von ExGetFirmwareEnvironmentVariable schlagen auf einer älteren BIOS-basierten Plattform immer fehl. 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ällig eindeutige GUID statisch zu generieren. Rufen Sie dann diese Routine auf, um nach einem bestimmten Variablennamen zu suchen, und geben Sie diese GUID als VendorGuid-Parameter an.
Auf einer Legacy-BIOS-basierten Plattform oder auf einer Plattform, die sowohl Legacy-BIOS als auch UEFI unterstützt, in der Windows jedoch 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 firmwarespezifischen Fehler wie STATUS_VARIABLE_NOT_FOUND fehl, um anzugeben, dass der Dummy-GUID-Namespace nicht vorhanden ist.
Wenn der Aufrufer einen Parameter ohne NULL-Attribute angibt, schreibt die Routine die Attribute der angegebenen Umgebungsvariable der Systemfirmware in den Speicherort, auf den von Attributen verwiesen wird. 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 wird, auf die von Attributen verwiesen wird, 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 UEFI-Website .
Wenn Sie einen Sicherungsdatenspeicher erstellen, können Sie diese Funktion verwenden, um alle Starteinstellungen für die Plattform zu speichern, sodass 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows 8. |
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
Weitere Informationen
ExSetFirmwareEnvironmentVariable