Função GetFirmwareEnvironmentVariableA (winbase.h)

  • Artigo

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

Sintaxe

DWORD GetFirmwareEnvironmentVariableA(
  [in]  LPCSTR lpName,
  [in]  LPCSTR lpGuid,
  [out] PVOID  pBuffer,
  [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-xxxxx}" em que 'x' representa um valor hexadecimal.

[out] pBuffer

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

[in] nSize

O tamanho do buffer pBuffer , em bytes.

Valor retornado

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

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 (Unified Extensible Firmware Interface). 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, 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, a leitura de variáveis UEFI (Unified Extensible Firmware Interface) também tem suporte de 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 GetFirmwareEnvironmentVariable 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 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.

GetFirmwareEnvironmentVariable é o equivalente ao modo de usuário da rotina do modo kernel ExGetFirmwareEnvironmentVariable .

Observação

O cabeçalho winbase.h define GetFirmwareEnvironmentVariable 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

   
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 (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Funções de informações do sistema