Função GetFirmwareEnvironmentVariableExA (winbase.h)

Artigo
11/20/2024

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

Sintaxe

DWORD GetFirmwareEnvironmentVariableExA(
  LPCSTR lpName,
  LPCSTR 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 "{xxxxxxx-xxxx-xxxx-xxxx-xxxxxx}" 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 de pValue, em bytes.

pdwAttribubutes

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

Valor de retorno

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.

Observações

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á em execução 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) de drivers User-Mode Driver Framework (UMDF). Não há suporte para escrever variáveis UEFI de drivers UMDF.

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 GetFirmwareEnvironmentVariableEx 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 "" 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 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 8 [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2012 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

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

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Compartilhar via