Edit

Share via

ExSetFirmwareEnvironmentVariable function (wdm.h)

  • Article

The ExSetFirmwareEnvironmentVariable routine sets the value of the specified system firmware environment variable.

Syntax

NTSTATUS ExSetFirmwareEnvironmentVariable(
  [in] PUNICODE_STRING VariableName,
  [in] LPGUID          VendorGuid,
  [in] PVOID           Value,
  [in] ULONG           ValueLength,
  [in] ULONG           Attributes
);

Parameters

[in] VariableName

A pointer to a UNICODE_STRING structure that contains the name of the specified environment variable.

[in] VendorGuid

A pointer to a GUID that identifies the vendor associated with the specified environment variable. Environment variables are grouped into namespaces based on their vendor GUIDs. Some hardware platforms might not support vendor GUIDs. On these platforms, all variables are grouped into one, common namespace, and the VendorGuid parameter is ignored.

[in] Value

A pointer to a caller-allocated buffer that contains the data value to write to the specified environment variable.

[in] ValueLength

The size, in bytes, of the data value contained in the Value buffer.

[in] Attributes

The attributes to assign to the specified environment variable. The VARIABLE_ATTRIBUTE_NON_VOLATILE attribute bit must be set or this call will fail. For more information about the attribute bits that are defined for this parameter, see Remarks in ExGetFirmwareEnvironmentVariable.

Return value

ExSetFirmwareEnvironmentVariable returns STATUS_SUCCESS if it is successful. Possible return values include the following error status codes.

Return code Description
STATUS_INSUFFICIENT_RESOURCES
 Available system resources are insufficient to complete the requested operation.
STATUS_INVALID_PARAMETER
 One of the parameters is not valid.
STATUS_NOT_IMPLEMENTED
 This routine is not supported on this platform.
STATUS_UNSUCCESSFUL
 The firmware returned an unrecognized error.

Remarks

The caller requires the system environment privilege (SE_SYSTEM_ENVIRONMENT_PRIVILEGE) to use this routine.

System firmware environment variables contain data values that are passed between the boot firmware environment implemented in the hardware platform and the operating-system loaders and other software that runs in the firmware environment. For more information, see Remarks in ExGetFirmwareEnvironmentVariable.

If you create a backup datastore, you can use the ExGetFirmwareEnvironmentVariable routine to save all the boot settings for the platform. Later, you can use ExSetFirmwareEnvironmentVariable to restore these settings if needed.

ExSetFirmwareEnvironmentVariable is the kernel-mode equivalent of the Win32 SetFirmwareEnvironmentVariable function.

Requirements

Requirement Value
Minimum supported client Available starting with Windows 8.
Target Platform Universal
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

See also

ExGetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariable

UNICODE_STRING