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-xxxxx-xxxxxx}". 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 da variável de ambiente de firmware.
[in] nSize
O tamanho do buffer de 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
Máscara de bits para definir atributos de variável UEFI associados à variável. Consulte também ESPECIFICAÇÃO UEFI 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.
Observação Variáveis com esse conjunto de atributos também deve ter VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS definido.
|
|
Indica erros relacionados ao hardware encontrados no 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 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 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 de retorno
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.
Observações
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 em 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
Nota
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 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 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2012 [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