Export (0) Print
Expand All
Expand Minimize

ExGetFirmwareEnvironmentVariable routine

The ExGetFirmwareEnvironmentVariable routine gets the value of the specified system firmware environment variable.

Syntax


NTSTATUS ExGetFirmwareEnvironmentVariable(
  _In_       PUNICODE_STRING VariableName,
  _In_       LPGUID VendorGuid,
  _Out_opt_  PVOID Value,
  _Inout_    PULONG ValueLength,
  _Out_opt_  PULONG 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 [out, optional]

A pointer to a caller-allocated buffer to which the routine writes the value of the specified environment variable.

ValueLength [in, out]

A pointer to a location that contains the buffer size. On entry, the location pointed to by this parameter contains the size, in bytes, of the caller-supplied Value buffer. Before exiting, the routine writes to this location the size, in bytes, of the variable value. If the routine returns STATUS_SUCCESS, the *ValueLength output value is the number of bytes of data written to the Value buffer. If the routine returns STATUS_BUFFER_TOO_SMALL, *ValueLength is the required buffer size.

Attributes [out, optional]

A pointer to a location to which the routine writes the attributes of the specified environment variable. This parameter is optional and can be set to NULL if the caller does not need the attributes. For more information, see Remarks.

Return value

ExGetFirmwareEnvironmentVariable 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_BUFFER_TOO_SMALL

The Value buffer is too small.

STATUS_VARIABLE_NOT_FOUND

The requested variable does not exist.

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

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.

The set of firmware environment variables that is available in a hardware platform depends on the boot firmware. The location of these environment variables is also specified by the firmware. For example, on a UEFI-based platform, NVRAM contains firmware environment variables that specify system boot settings. For information about specific variables used, see the Unified Extensible Firmware Interface Specification at the UEFI website. For more information about UEFI and Windows, see UEFI and Windows.

Firmware environment variables are not supported on a legacy BIOS-based platform. Calls to ExGetFirmwareEnvironmentVariable always fail on a legacy BIOS-based platform; they also fail if Windows was installed using the legacy BIOS on a platform that supports both legacy BIOS and UEFI. To identify these conditions, call the function with a dummy VariableName string (for example, an empty string) and a dummy GUID such as

"{00000000-0000-0000-0000-000000000000}"

for the VendorGuid parameter. On a legacy BIOS-based platform, or on a platform that supports both legacy BIOS and UEFI but in which Windows was installed using the legacy BIOS, the function will fail with STATUS_NOT_IMPLEMENTED. On a UEFI-based platform, the function will fail with an error specific to the firmware, such as STATUS_VARIABLE_NOT_FOUND, to indicate that the dummy GUID namespace does not exist.

If the caller specifies a non-NULL Attributes parameter, the routine writes the attributes of the specified system firmware environment variable to the location pointed to by Attributes. Version 2.3.1 of the UEFI specification defines the following attributes for firmware environment variables.

Variable nameValue
EFI_VARIABLE_NON_VOLATILE0x00000001
EFI_VARIABLE_BOOTSERVICE_ACCESS0x00000002
EFI_VARIABLE_RUNTIME_ACCESS0x00000004
EFI_VARIABLE_HARDWARE_ERROR_RECORD0x00000008
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS0x00000010
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS0x00000020
EFI_VARIABLE_APPEND_WRITE0x00000040

 

These attribute values are defined as flag bits. The value written to the ULONG variable pointed to by Attributes is either zero or the bitwise OR of one or more attributes in the preceding table. For more information, see the UEFI specification at the UEFI website.

If you create a backup datastore, you can use this function to save all the boot settings for the platform so they can be restored by calling the ExSetFirmwareEnvironmentVariable routine if needed.

ExGetFirmwareEnvironmentVariable is the kernel-mode equivalent of the Win32 GetFirmwareEnvironmentVariable 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

ExSetFirmwareEnvironmentVariable
GetFirmwareEnvironmentVariable
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft