Share via

Função SetFirmwareEnvironmentVariableW (winbase.h)

  • Artigo

Define o valor da variável de ambiente de firmware especificada.

Sintaxe

BOOL SetFirmwareEnvironmentVariableW(
  [in] LPCWSTR lpName,
  [in] LPCWSTR lpGuid,
  [in] PVOID   pValue,
  [in] DWORD   nSize
);

Parâmetros

[in] lpName

O nome da variável de ambiente de firmware. O ponteiro não deve ser NULL.

[in] lpGuid

O GUID que representa o namespace da variável de ambiente de firmware. O GUID deve ser uma cadeia de caracteres no formato "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx}". Se o sistema não der suporte a namespaces baseados em GUID, esse parâmetro será ignorado.

[in] pValue

Um ponteiro para o novo valor para a variável de ambiente de firmware.

[in] nSize

O tamanho do buffer pBuffer , em bytes. Se esse parâmetro for zero, a variável de ambiente de firmware será excluída.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Os códigos de erro possíveis incluem ERROR_INVALID_FUNCTION.

Comentários

A partir do Windows 10, versão 1803, os aplicativos Universais do Windows podem ler e gravar variáveis de firmware UEFI. Consulte Acessar variáveis de firmware UEFI de um Aplicativo Universal do Windows para obter detalhes.

A partir do Windows 10, versão 1803, também há suporte para a leitura de variáveis de firmware UEFI de drivers User-Mode Driver Framework (UMDF). Não há suporte para a gravação de variáveis de firmware UEFI de drivers UMDF.

Para gravar uma variável de ambiente de firmware, a conta de usuário em que o aplicativo está sendo executado deve ter o privilégio SE_SYSTEM_ENVIRONMENT_NAME . Um aplicativo Universal do Windows deve ser executado de uma conta de administrador e seguir os requisitos descritos em Acessar variáveis de firmware UEFI de um Aplicativo Universal do Windows.

O conjunto exato de variáveis de ambiente de firmware é determinado pelo firmware de inicialização. O local dessas variáveis de ambiente também é especificado pelo firmware. Por exemplo, em um sistema baseado em UEFI, o NVRAM contém variáveis de ambiente de firmware que especificam as configurações de inicialização do sistema. Para obter informações sobre variáveis específicas usadas, consulte a especificação UEFI. Para obter mais informações sobre UEFI e Windows, consulte UEFI e Windows.

Não há suporte para variáveis de firmware em um sistema herdado baseado em BIOS. A função SetFirmwareEnvironmentVariable sempre falhará em um sistema herdado baseado em BIOS ou se o Windows foi instalado usando BIOS herdado em um sistema que dá suporte ao BIOS herdado e à UEFI. Para identificar essas condições, chame a função com um nome de ambiente de firmware fictício, como uma cadeia de caracteres vazia ("") para o parâmetro lpName e um GUID fictício, como "{00000000-0000-0000-0000-000000000000}" para o parâmetro lpGuid . Em um sistema herdado baseado em BIOS ou em um sistema que dá suporte ao BIOS herdado e à UEFI em que o Windows foi instalado usando BIOS herdado, a função falhará com ERROR_INVALID_FUNCTION. Em um sistema baseado em UEFI, a função falhará com um erro específico para o firmware, como ERROR_NOACCESS, para indicar que o namespace guid fictício não existe.

SetFirmwareEnvironmentVariable é o equivalente do modo de usuário da rotina exSetFirmwareEnvironmentVariable kernel-mode.

Observação

O cabeçalho winbase.h define SetFirmwareEnvironmentVariable como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista, Windows XP com SP1 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho winbase.h (incluir Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Acessar variáveis de firmware UEFI de um aplicativo Universal do Windows

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Funções de informações do sistema