Функция ExGetFirmwareEnvironmentVariable (wdm.h)

Статья
03/14/2023

Подпрограмма ExGetFirmwareEnvironmentVariable получает значение указанной переменной среды встроенного ПО системы.

Синтаксис

NTSTATUS ExGetFirmwareEnvironmentVariable(
  [in]            PUNICODE_STRING VariableName,
  [in]            LPGUID          VendorGuid,
  [out, optional] PVOID           Value,
  [in, out]       PULONG          ValueLength,
  [out, optional] PULONG          Attributes
);

Параметры

[in] VariableName

Указатель на структуру UNICODE_STRING , содержащую имя указанной переменной среды.

[in] VendorGuid

Указатель на GUID, который идентифицирует поставщика, связанного с указанной переменной среды. Переменные среды группируются в пространства имен на основе идентификаторов GUID поставщика. Некоторые аппаратные платформы могут не поддерживать идентификаторы GUID поставщиков. На этих платформах все переменные группируются в одно общее пространство имен, а параметр VendorGuid игнорируется.

[out, optional] Value

Указатель на буфер, выделенный вызывающим объектом, в который подпрограмма записывает значение указанной переменной среды.

[in, out] ValueLength

Указатель на расположение, содержащее размер буфера. В записи расположение, на которое указывает этот параметр, содержит размер буфера значений , предоставленного вызывающим объектом , в байтах. Перед выходом подпрограмма записывает в это расположение размер (в байтах) значения переменной. Если подпрограмма возвращает STATUS_SUCCESS, выходное значение *ValueLength — это количество байтов данных, записанных в буфер значений . Если подпрограмма возвращает STATUS_BUFFER_TOO_SMALL, *ValueLength является требуемым размером буфера.

[out, optional] Attributes

Указатель на расположение, в которое подпрограмма записывает атрибуты указанной переменной среды. Этот параметр является необязательным и может иметь значение NULL, если вызывающий объект не требует атрибутов. Дополнительные сведения см. в подразделе "Примечания".

Возвращаемое значение

ExGetFirmwareEnvironmentVariable возвращает STATUS_SUCCESS в случае успешного выполнения. Возможные возвращаемые значения включают следующие коды состояния ошибок.

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	Доступных системных ресурсов недостаточно для выполнения запрошенной операции.
STATUS_BUFFER_TOO_SMALL	Буфер значений слишком мал.
STATUS_VARIABLE_NOT_FOUND	Запрошенная переменная не существует.
STATUS_INVALID_PARAMETER	Один из параметров недопустим.
STATUS_NOT_IMPLEMENTED	Эта подпрограмма не поддерживается на этой платформе.
STATUS_UNSUCCESSFUL	Встроенное ПО вернуло нераспознанную ошибку.

Переменные среды встроенного ПО системы содержат значения данных, передаваемые между средой загрузки встроенного ПО, реализованной на аппаратной платформе, и загрузчиками операционной системы и другим программным обеспечением, работающим в среде встроенного ПО.

Набор переменных среды встроенного ПО, доступных на аппаратной платформе, зависит от встроенного ПО загрузки. Расположение этих переменных среды также определяется встроенным ПО. Например, на платформе на основе UEFI NVRAM содержит переменные среды встроенного ПО, определяющие параметры загрузки системы. Сведения о конкретных используемых переменных см. в спецификации интерфейса единого расширяемого встроенного ПО на веб-сайте UEFI . Дополнительные сведения о UEFI и Windows см. в разделе UEFI и Windows.

Переменные среды встроенного ПО не поддерживаются на устаревшей платформе на основе BIOS. Вызовы ExGetFirmwareEnvironmentVariable всегда завершаются сбоем на устаревшей платформе на основе BIOS; Они также завершаются ошибкой, если Windows была установлена с использованием устаревшей ВЕРСИИ BIOS на платформе, поддерживающей как устаревшие BIOS, так и UEFI. Чтобы определить эти условия, сначала используйте uuidgen или аналогичное средство для статического создания случайного уникального GUID. Затем вызовите эту подпрограмму, чтобы найти имя конкретной переменной, указав этот GUID в качестве параметра VendorGuid .

На устаревшей платформе на основе BIOS или на платформе, которая поддерживает как устаревшие BIOS, так и UEFI, но в которой Windows была установлена с помощью устаревшей BIOS, функция завершится сбоем с STATUS_NOT_IMPLEMENTED. На платформе на основе UEFI функция завершится ошибкой, относящейся к встроенному ПО, например STATUS_VARIABLE_NOT_FOUND, чтобы указать, что фиктивное пространство имен GUID не существует.

Если вызывающий объект указывает параметр Attributes , отличный от NULL, подпрограмма записывает атрибуты указанной переменной среды встроенного ПО системы в расположение, на которое указывает Атрибуты. Версия 2.3.1 спецификации UEFI определяет следующие атрибуты для переменных среды встроенного ПО.

Имя переменной	Значение
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

Эти значения атрибутов определяются как биты флагов. Значение, записанное в переменную ULONG, на которую указывает Атрибуты , равно нулю или побитовой ИЛИ одного или нескольких атрибутов в предыдущей таблице. Дополнительные сведения см. в спецификации UEFI на веб-сайте UEFI .

При создании резервного хранилища данных можно использовать эту функцию для сохранения всех параметров загрузки для платформы, чтобы их можно было восстановить, вызвав подпрограмму ExSetFirmwareEnvironmentVariable при необходимости.

ExGetFirmwareEnvironmentVariable — это эквивалент функции Win32 GetFirmwareEnvironmentVariable в режиме ядра.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

См. также раздел

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING