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

Подпрограмма 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 содержит переменные среды встроенного ПО, указывающие параметры загрузки системы. Сведения об определенных переменных, используемых, см. на веб-сайте веб-сайте UE FI унифицированного расширяемого интерфейса встроенного ПО. Дополнительные сведения о 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 не существует.

Если вызывающий объект задает параметр атрибутов, отличных от 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 (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

См. также

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING