Функция 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 должен быть строкой в формате "{xxxx-xxxx}". Если система не поддерживает пространства имен на основе GUID, этот параметр игнорируется. Указатель не должен быть null.
[in] pValue
Указатель на новое значение для переменной среды встроенного ПО.
[in] nSize
Размер буфера pValue
[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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 8 [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2012 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |
См. также
переменные встроенного ПО UEFI из универсального приложения Для Windows