Função ExGetFirmwareEnvironmentVariable (wdm.h)

A rotina ExGetFirmwareEnvironmentVariable obtém o valor da variável de ambiente de firmware do sistema especificada.

Sintaxe

NTSTATUS ExGetFirmwareEnvironmentVariable(
  [in]            PUNICODE_STRING VariableName,
  [in]            LPGUID          VendorGuid,
  [out, optional] PVOID           Value,
  [in, out]       PULONG          ValueLength,
  [out, optional] PULONG          Attributes
);

Parâmetros

[in] VariableName

Um ponteiro para uma estrutura UNICODE_STRING que contém o nome da variável de ambiente especificada.

[in] VendorGuid

Um ponteiro para um GUID que identifica o fornecedor associado à variável de ambiente especificada. As variáveis de ambiente são agrupadas em namespaces com base em seus GUIDs de fornecedor. Algumas plataformas de hardware podem não dar suporte a GUIDs do fornecedor. Nessas plataformas, todas as variáveis são agrupadas em um namespace comum e o parâmetro VendorGuid é ignorado.

[out, optional] Value

Um ponteiro para um buffer alocado pelo chamador no qual a rotina grava o valor da variável de ambiente especificada.

[in, out] ValueLength

Um ponteiro para um local que contém o tamanho do buffer. Na entrada, o local apontado por esse parâmetro contém o tamanho, em bytes, do buffer De valor fornecido pelo chamador. Antes de sair, a rotina grava nesse local o tamanho, em bytes, do valor da variável. Se a rotina retornar STATUS_SUCCESS, o valor de saída *ValueLength será o número de bytes de dados gravados no buffer Valor . Se a rotina retornar STATUS_BUFFER_TOO_SMALL, *ValueLength será o tamanho do buffer necessário.

[out, optional] Attributes

Um ponteiro para um local no qual a rotina grava os atributos da variável de ambiente especificada. Esse parâmetro é opcional e pode ser definido como NULL se o chamador não precisar dos atributos. Para obter mais informações, consulte Comentários.

Retornar valor

ExGetFirmwareEnvironmentVariable retornará STATUS_SUCCESS se for bem-sucedido. Os possíveis valores retornados incluem o seguinte erro status códigos.

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	Os recursos do sistema disponíveis são insuficientes para concluir a operação solicitada.
STATUS_BUFFER_TOO_SMALL	O buffer Valor é muito pequeno.
STATUS_VARIABLE_NOT_FOUND	A variável solicitada não existe.
STATUS_INVALID_PARAMETER	Um dos parâmetros não é válido.
STATUS_NOT_IMPLEMENTED	Não há suporte para essa rotina nesta plataforma.
STATUS_UNSUCCESSFUL	O firmware retornou um erro não reconhecido.

Comentários

As variáveis de ambiente de firmware do sistema contêm valores de dados passados entre o ambiente de firmware de inicialização implementado na plataforma de hardware e os carregadores do sistema operacional e outros softwares executados no ambiente de firmware.

O conjunto de variáveis de ambiente de firmware que está disponível em uma plataforma de hardware depende do firmware de inicialização. A localização dessas variáveis de ambiente também é especificada pelo firmware. Por exemplo, em uma plataforma baseada 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 da Interface de Firmware Extensível Unificada no site da UEFI . Para obter mais informações sobre UEFI e Windows, consulte UEFI e Windows.

Não há suporte para variáveis de ambiente de firmware em uma plataforma herdada baseada em BIOS. As chamadas para ExGetFirmwareEnvironmentVariable sempre falham em uma plataforma herdada baseada em BIOS; eles também falharão se o Windows tiver sido instalado usando o BIOS herdado em uma plataforma que dá suporte ao BIOS herdado e à UEFI. Para identificar essas condições, primeiro use uuidgen ou uma ferramenta semelhante para gerar um GUID exclusivo aleatório estaticamente. Em seguida, chame essa rotina para procurar um nome de variável específico, fornecendo esse GUID como o parâmetro VendorGuid .

Em uma plataforma herdada baseada em BIOS ou em uma plataforma que dá suporte ao BIOS herdado e à UEFI, mas na qual o Windows foi instalado usando o BIOS herdado, a função falhará com STATUS_NOT_IMPLEMENTED. Em uma plataforma baseada em UEFI, a função falhará com um erro específico ao firmware, como STATUS_VARIABLE_NOT_FOUND, para indicar que o namespace guid fictício não existe.

Se o chamador especificar um parâmetro atributos não NULL, a rotina gravará os atributos da variável de ambiente de firmware do sistema especificada no local apontado por Atributos. A versão 2.3.1 da especificação UEFI define os atributos a seguir para variáveis de ambiente de firmware.

Nome da variável	Valor
EFI_VARIABLE_NON_VOLATILE	0x00000001
EFI_VARIABLE_BOOTSERVICE_ACCESS	0x00000002
EFI_VARIABLE_RUNTIME_ACCESS	0x00000004
EFI_VARIABLE_HARDWARE_ERROR_RECORD	0x00000008
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS	0x00000010
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS	0x00000020
EFI_VARIABLE_APPEND_WRITE	0x00000040

Esses valores de atributo são definidos como bits de sinalizador. O valor gravado na variável ULONG apontada por Attributes é zero ou o OR bit a bit de um ou mais atributos na tabela anterior. Para obter mais informações, consulte a especificação UEFI no site da UEFI .

Se você criar um armazenamento de dados de backup, poderá usar essa função para salvar todas as configurações de inicialização da plataforma para que elas possam ser restauradas chamando a rotina ExSetFirmwareEnvironmentVariable , se necessário.

ExGetFirmwareEnvironmentVariable é o equivalente ao modo kernel da função Win32 GetFirmwareEnvironmentVariable .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Confira também

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING