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