Expand Minimize

ExSetFirmwareEnvironmentVariable routine

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

VariableName [in]

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

VendorGuid [in]

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.

Value [in]

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

ValueLength [in]

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

Attributes [in]

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 codeDescription
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

Version

Available starting with Windows 8.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

See also

ExGetFirmwareEnvironmentVariable
SetFirmwareEnvironmentVariable
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft