Função SetFirmwareEnvironmentVariableExA (winbase.h)
Define o valor da variável de ambiente de firmware especificada como os atributos que indicam como essa variável é armazenada e mantida.
Sintaxe
BOOL SetFirmwareEnvironmentVariableExA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
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 "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx}". Se o sistema não der suporte a namespaces baseados em GUID, esse parâmetro será ignorado. O ponteiro não deve ser NULL.
[in] pValue
Um ponteiro para o novo valor para a variável de ambiente de firmware.
[in] nSize
O tamanho do buffer pValue , em bytes. A menos que o atributo de variável VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS ou VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS seja definido por meio de dwAttributes, definir esse valor como zero resultará na exclusão dessa variável.
[in] dwAttributes
Bitmask para definir atributos de variável UEFI associados à variável. Consulte também UEFI Spec 2.3.1, Seção 7.2.
| Valor | Significado |
|---|---|
|
A variável de ambiente de firmware é armazenada em memória não volátil (por exemplo, NVRAM). |
|
A variável de ambiente de firmware pode ser acessada durante o serviço de inicialização. |
|
A variável de ambiente de firmware pode ser acessada em runtime.
Nota Variáveis com esse conjunto de atributos também devem ter VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS definidos.
|
|
Indica erros relacionados ao hardware encontrados em runtime. |
|
Indica um requisito de autenticação que deve ser atendido antes de gravar nessa variável de ambiente de firmware. Para obter mais informações, consulte a especificação UEFI 2.3.1. |
|
Indica os requisitos de autenticação e carimbo de data/hora que devem ser atendidos antes de gravar nessa variável de ambiente de firmware. Quando esse atributo for definido, o buffer, representado por pValue, começará com uma instância de um descritor de EFI_VARIABLE_AUTHENTICATION_2 completo (e serializado). Para obter mais informações, consulte a especificação UEFI 2.3.1. |
|
Acrescente uma variável de ambiente existente com o valor de pValue. Se o firmware não der suporte à operação, SetFirmwareEnvironmentVariableEx retornará ERROR_INVALID_FUNCTION. |
Valor retornado
Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.
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.
Comentários
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.
A partir do Windows 10, versão 1803, também há suporte para a leitura de variáveis de firmware UEFI de drivers User-Mode Driver Framework (UMDF). Não há suporte para a gravação de variáveis de firmware UEFI de drivers UMDF.
Para gravar 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 de uma conta de administrador e seguir os requisitos descritos em Acessar variáveis de firmware UEFI de um Aplicativo Universal do Windows.
O método correto de alterar os atributos de uma variável é excluir a variável e recriá-la com atributos diferentes.
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 SetFirmwareEnvironmentVariableEx 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 "{00000000-0000-0000-0000-000000000000}" 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 para o firmware, como ERROR_NOACCESS, para indicar que o namespace guid fictício não existe.
Observação
O cabeçalho winbase.h define SetFirmwareEnvironmentVariableEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Acessar variáveis de firmware UEFI de um aplicativo Universal do Windows
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de