Share via

Função GetFirmwareEnvironmentVariableExW (winbase.h)

  • Artigo

Recupera o valor da variável de ambiente de firmware especificada e seus atributos.

Sintaxe

DWORD GetFirmwareEnvironmentVariableExW(
  LPCWSTR lpName,
  LPCWSTR lpGuid,
  PVOID   pBuffer,
  DWORD   nSize,
  PDWORD  pdwAttribubutes
);

Parâmetros

lpName

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

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-xxxxx}" em que 'x' representa um valor hexadecimal. O ponteiro não deve ser NULL.

pBuffer

Um ponteiro para um buffer que recebe o valor da variável de ambiente de firmware especificada.

nSize

O tamanho do buffer pValue , em bytes.

pdwAttribubutes

Bitmask identificando atributos de variável UEFI associados à variável. Consulte SetFirmwareEnvironmentVariableEx para obter a definição de bitmask.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de bytes armazenados no buffer pValue .

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.

Para ler uma variável de ambiente de firmware UEFI, 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 em uma conta de administrador e seguir os requisitos descritos em Acessar variáveis de firmware UEFI de um Aplicativo Universal do Windows.

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

O conjunto exato de variáveis de ambiente de firmware é determinado pelo firmware de inicialização. A localização dessas variáveis de ambiente também é especificada 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 GetFirmwareEnvironmentVariableEx sempre falhará em um sistema herdado baseado em BIOS ou se o Windows foi instalado usando o 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 o 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 ao firmware, como ERROR_NOACCESS, para indicar que o namespace guid fictício não existe.

Se você estiver criando um aplicativo de backup, poderá usar essa função para salvar todas as configurações de inicialização do sistema para que elas possam ser restauradas usando a função SetFirmwareEnvironmentVariable , se necessário.

Observação

O cabeçalho winbase.h define GetFirmwareEnvironmentVariableEx 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 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho winbase.h (inclua 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