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

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

Синтаксис

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

Параметры

[in] lpName

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

[in] lpGuid

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

[in] pValue

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

[in] nSize

Размер буфера pBuffer в байтах. Если этот параметр равен нулю, переменная среды встроенного ПО удаляется.

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

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

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав 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. Функция SetFirmwareEnvironmentVariable всегда будет завершаться сбоем в устаревшей системе на основе 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 — это пользовательский режим, эквивалентный подпрограмме режима ядра ExSetFirmwareEnvironmentVariable .

Примечание

Заголовок winbase.h определяет SetFirmwareEnvironmentVariable в качестве псевдонима, который автоматически выбирает версию 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

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

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