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

Статья
03/08/2023

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

Синтаксис

DWORD GetFirmwareEnvironmentVariableA(
  [in]  LPCSTR lpName,
  [in]  LPCSTR lpGuid,
  [out] PVOID  pBuffer,
  [in]  DWORD  nSize
);

Параметры

[in] lpName

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

[in] lpGuid

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

[out] pBuffer

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

[in] nSize

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

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

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

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

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

Чтобы считывать переменную среды встроенного ПО, учетная запись пользователя, в которой выполняется приложение, должна иметь права 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. Функция GetFirmwareEnvironmentVariable всегда будет завершаться сбоем в устаревшей системе на основе 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 .

GetFirmwareEnvironmentVariable — это пользовательский режим, эквивалентный подпрограмме в режиме ядра ExGetFirmwareEnvironmentVariable .

Примечание

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

Требования


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

См. также

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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Функции сведений о системе