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


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

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

Синтаксис

BOOL SetFirmwareEnvironmentVariableExA(
  [in] LPCSTR lpName,
  [in] LPCSTR lpGuid,
  [in] PVOID  pValue,
  [in] DWORD  nSize,
  [in] DWORD  dwAttributes
);

Параметры

[in] lpName

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

[in] lpGuid

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

[in] pValue

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

[in] nSize

Размер буфера pValue в байтах. Если атрибут переменной VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS или VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS не задан с помощью dwAttributes, установка этого значения в ноль приведет к удалению этой переменной.

[in] dwAttributes

Битовая маска для задания атрибутов переменных UEFI, связанных с переменной. См. также спецификацию UEFI 2.3.1, раздел 7.2.

Значение Значение
VARIABLE_ATTRIBUTE_NON_VOLATILE
0x00000001
Переменная среды встроенного ПО хранится в энергонезависимой памяти (например, NVRAM).
VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS
0x00000002
Доступ к переменной среды встроенного ПО можно получить во время загрузки службы.
VARIABLE_ATTRIBUTE_RUNTIME_ACCESS
0x00000004
Доступ к переменной среды встроенного ПО можно получить во время выполнения.
Примечание Переменные с этим набором атрибутов также должны иметь VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS набор.
 
VARIABLE_ATTRIBUTE_HARDWARE_ERROR_RECORD
0x00000008
Указывает на ошибки, связанные с оборудованием, возникшие во время выполнения.
VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS
0x00000010
Указывает требование проверки подлинности, которое необходимо выполнить перед записью в эту переменную среды встроенного ПО. Дополнительные сведения см. в спецификации UEFI 2.3.1.
VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
0x00000020
Указывает требования к проверке подлинности и меткам времени, которые должны быть выполнены перед записью в эту переменную среды встроенного ПО. Если этот атрибут задан, буфер, представленный pValue, будет начинаться с экземпляра полного (и сериализованного) дескриптора EFI_VARIABLE_AUTHENTICATION_2. Дополнительные сведения см. в спецификации UEFI 2.3.1.
VARIABLE_ATTRIBUTE_APPEND_WRITE
0x00000040
Добавьте существующую переменную среды со значением pValue. Если встроенное ПО не поддерживает операцию, setFirmwareEnvironmentVariableEx вернет ERROR_INVALID_FUNCTION.

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

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

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

Комментарии

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

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

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

Правильный метод изменения атрибутов переменной заключается в удалении переменной и ее повторном создании с различными атрибутами.

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

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

Примечание

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

Требования

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

См. также

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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable