Função GetFirmwareEnvironmentVariableW (winbase.h)

Artigo
11/20/2024

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

Sintaxe

DWORD GetFirmwareEnvironmentVariableW(
  [in]  LPCWSTR lpName,
  [in]  LPCWSTR 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 "{xxxxxxx-xxxx-xxxx-xxxx-xxxxxx}" 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 de pBuffer , em bytes.

Valor de retorno

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.

Observações

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

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

Nota

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 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 Vista, Windows XP com SP1 [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Funções de informações do sistema

Compartilhar via