Функция GetFirmwareEnvironmentVariableExA (winbase.h)

Статья
08/27/2023

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

Синтаксис

DWORD GetFirmwareEnvironmentVariableExA(
  LPCSTR lpName,
  LPCSTR lpGuid,
  PVOID  pBuffer,
  DWORD  nSize,
  PDWORD pdwAttribubutes
);

Параметры

lpName

Имя переменной среды встроенного ПО. Указатель не должен иметь значение NULL.

lpGuid

GUID, представляющий пространство имен переменной среды встроенного ПО. Guid должен быть строкой в формате "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxx}", где "x" представляет шестнадцатеричное значение. Указатель не должен иметь значение NULL.

pBuffer

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

nSize

Размер буфера pValue в байтах.

pdwAttribubutes

Битовая маска, определяющая атрибуты переменной UEFI, связанные с переменной. Определение битовой маски см. в разделе SetFirmwareEnvironmentVariableEx .

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

Если функция выполнена успешно, возвращаемое значение — это количество байтов, хранящихся в буфере pValue .

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Возможные коды ошибок включают ERROR_INVALID_FUNCTION.

Начиная с Windows 10 версии 1803, универсальные приложения для Windows могут считывать и записывать переменные встроенного ПО UEFI. Дополнительные сведения см. в статье Доступ к переменным встроенного ПО UEFI из универсального приложения для Windows .

Для чтения переменной среды встроенного ПО UEFI учетная запись пользователя, в которой выполняется приложение, должна иметь права SE_SYSTEM_ENVIRONMENT_NAME . Универсальное приложение для Windows должно запускаться из учетной записи администратора и соответствовать требованиям, изложенным в разделе Доступ к переменным встроенного ПО UEFI из универсального приложения для Windows.

Начиная с Windows 10 версии 1803, чтение переменных UEFI также поддерживается из драйверов User-Mode Driver Framework (UMDF). Запись переменных UEFI из драйверов UMDF не поддерживается.

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

Переменные встроенного ПО не поддерживаются в устаревшей системе на основе BIOS. Функция GetFirmwareEnvironmentVariableEx всегда будет завершаться сбоем в устаревшей системе на основе BIOS или, если Windows была установлена с помощью устаревшей версии BIOS в системе, поддерживающей как устаревшие BIOS, так и UEFI. Чтобы определить эти условия, вызовите функцию с фиктивным именем среды встроенного ПО, например пустой строкой ("") для параметра lpName и фиктивным ИДЕНТИФИКАТОРом GUID, например "{00000000-0000-0000-0000-000000000000}" для параметра lpGuid . В устаревшей системе на основе BIOS или в системе, поддерживающей как устаревшие BIOS, так и UEFI, где Windows была установлена с помощью устаревшей BIOS, функция завершится сбоем с ERROR_INVALID_FUNCTION. В системе на основе UEFI функция завершится ошибкой, относящейся к встроенному ПО, например ERROR_NOACCESS, чтобы указать, что фиктивное пространство имен GUID не существует.

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

Примечание

Заголовок winbase.h определяет GetFirmwareEnvironmentVariableEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

Доступ к переменным встроенного ПО UEFI из универсального приложения для Windows

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Share via