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 de 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 Value 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 Value. Se a rotina retornar STATUS_BUFFER_TOO_SMALL, * ValueLength é 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.
Valor de retorno
ExGetFirmwareEnvironmentVariable retornará STATUS_SUCCESS se for bem-sucedido. Os possíveis valores retornados incluem os seguintes códigos de status de erro.
| 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. |
Observações
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. O local dessas variáveis de ambiente também é especificado 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 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 foi 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 Attributes. 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 apontado por Attributes é zero ou or bit a bit de um ou mais atributos na tabela anterior. Para obter mais informações, consulte a especificação UEFI no site 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 do modo kernel da função de GetFirmwareEnvironmentVariable do Win32.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 8. |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
Consulte também
ExSetFirmwareEnvironmentVariable