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

Статья
11/20/2024

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

Синтаксис

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

Параметры

lpName

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

lpGuid

GUID, представляющий пространство имен переменной среды встроенного ПО. GUID должен быть строкой в формате "{xxxx-xxxx-xxxx-xxxx}", где "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]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Поделиться через