Export (0) Print
Expand All

SetFirmwareEnvironmentVariableEx function

Sets the value of the specified firmware environment variable as the attributes that indicate how this variable is stored and maintained.

Syntax


BOOL WINBASEAPI SetFirmwareEnvironmentVariableEx(
  _In_  LPCTSTR lpName,
  _In_  LPCTSTR lpGuid,
  _In_  PVOID pValue,
  _In_  DWORD nSize,
  _In_  DWORD dwAttributes
);

Parameters

lpName [in]

The name of the firmware environment variable. The pointer must not be NULL.

lpGuid [in]

The GUID that represents the namespace of the firmware environment variable. The GUID must be a string in the format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}". If the system does not support GUID-based namespaces, this parameter is ignored. The pointer must not be NULL.

pValue [in]

A pointer to the new value for the firmware environment variable.

nSize [in]

The size of the pValue buffer, in bytes. Unless the VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS, or VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS variable attribute is set via dwAttributes, setting this value to zero will result in the deletion of this variable.

dwAttributes [in]

Bitmask to set UEFI variable attributes associated with the variable. See also UEFI Spec 2.3.1, Section 7.2.

ValueMeaning
VARIABLE_ATTRIBUTE_NON_VOLATILE
0x00000001

The firmware environment variable is stored in non-volatile memory (e.g. NVRAM).

VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS
0x00000002

The firmware environment variable can be accessed during boot service.

VARIABLE_ATTRIBUTE_RUNTIME_ACCESS
0x00000004

The firmware environment variable can be accessed at runtime.

Note  Variables with this attribute set, must also have VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS set.

VARIABLE_ATTRIBUTE_HARDWARE_ERROR_RECORD
0x00000008

Indicates hardware related errors encountered at runtime.

VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS
0x00000010

Indicates an authentication requirement that must be met before writing to this firmware environment variable. For more information see, UEFI spec 2.3.1.

VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
0x00000020

Indicates authentication and time stamp requirements that must be met before writing to this firmware environment variable. When this attribute is set, the buffer, represented by pValue, will begin with an instance of a complete (and serialized) EFI_VARIABLE_AUTHENTICATION_2 descriptor. For more information see, UEFI spec 2.3.1.

VARIABLE_ATTRIBUTE_APPEND_WRITE
0x00000040

Append an existing environment variable with the value of pValue. If the firmware does not support the operation, then SetFirmwareEnvironmentVariableEx will return ERROR_INVALID_FUNCTION.

 

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Possible error codes include ERROR_INVALID_FUNCTION.

Remarks

The correct method of changing the attributes of a variable is to delete the variable and recreate it with different attributes.

The exact set of firmware environment variables is determined by the boot firmware. The location of these environment variables is also specified by the firmware. For example, on a UEFI-based system, NVRAM contains firmware environment variables that specify system boot settings. For information about specific variables used, see the UEFI specification. For more information about UEFI and Windows, see UEFI and Windows.

Firmware variables are not supported on a legacy BIOS-based system. The SetFirmwareEnvironmentVariableEx function will always fail on a legacy BIOS-based system, or if Windows was installed using legacy BIOS on a system that supports both legacy BIOS and UEFI. To identify these conditions, call the function with a dummy firmware environment name such as an empty string ("") for the lpName parameter and a dummy GUID such as "{00000000-0000-0000-0000-000000000000}" for the lpGuid parameter. On a legacy BIOS-based system, or on a system that supports both legacy BIOS and UEFI where Windows was installed using legacy BIOS, the function will fail with ERROR_INVALID_FUNCTION. On a UEFI-based system, the function will fail with an error specific to the firmware, such as ERROR_NOACCESS, to indicate that the dummy GUID namespace does not exist.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

SetFirmwareEnvironmentVariableExW (Unicode) and SetFirmwareEnvironmentVariableExA (ANSI)

See also

GetFirmwareEnvironmentVariableEx
SetFirmwareEnvironmentVariable

 

 

Community Additions

ADD
Show:
© 2014 Microsoft