Функция 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.
| Значение | Значение |
|---|---|
|
Переменная среды встроенного ПО хранится в энергонезависимой памяти (например, NVRAM). |
|
Доступ к переменной среды встроенного ПО можно получить во время загрузки службы. |
|
Доступ к переменной среды встроенного ПО можно получить во время выполнения.
Примечание Переменные с этим набором атрибутов также должны иметь VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS набор.
|
|
Указывает на ошибки, связанные с оборудованием, возникшие во время выполнения. |
|
Указывает требование проверки подлинности, которое необходимо выполнить перед записью в эту переменную среды встроенного ПО. Дополнительные сведения см. в спецификации UEFI 2.3.1. |
|
Указывает требования к проверке подлинности и меткам времени, которые должны быть выполнены перед записью в эту переменную среды встроенного ПО. Если этот атрибут задан, буфер, представленный pValue, будет начинаться с экземпляра полного (и сериализованного) дескриптора EFI_VARIABLE_AUTHENTICATION_2. Дополнительные сведения см. в спецификации UEFI 2.3.1. |
|
Добавьте существующую переменную среды со значением 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