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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] lpName

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

[in] lpGuid

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

[in] pValue

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

[in] nSize

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

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

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

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите 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]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

системные информационные функции

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