IWDFDevice2::AssignSxWakeSettings method

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The AssignSxWakeSettings method provides driver-supplied information about a device's ability to trigger a wake signal while both the device and the system are in a low-power state.

Syntax

Parameters

DxState [in]

A DEVICE_POWER_STATE-typed enumerator that identifies the low device power state that the device will enter when the system power state drops to a wakeable low-power state. The value of DxState cannot be PowerDeviceD0. DEVICE_POWER_STATE values are defined in wdm.h.

A WDF_TRI_STATE-typed enumerator that indicates whether the device can wake the system (that is, restore the system to S0) when the system is in a low-power state. This member can have one of the following values:

WdfTrue - Waking the system is enabled.

WdfFalse - Waking the system is disabled.

WdfUseDefault - Waking the system is initially enabled by default; but if the UserControlOfWakeSettings member is set to WakeAllowUserControl, the user's setting or driver's INF file overrides the initial value.

The DxState parameter specifies an invalid device power state, or the bus driver indicates that the device cannot trigger a wake signal,

This method might return one of the other values that Winerror.h contains.

Remarks

The first time a driver calls AssignSxWakeSettings, the following actions occur:

The framework stores the parameter values.

If the UserControlOfWakeSettings parameter is set to WakeAllowUserControl and if the Enabled parameter is set to WdfUseDefault, the framework reads the registry to find out if the user has enabled waking the system.

During subsequent calls to AssignSxWakeSettings, the framework does not store the value of the UserControlOfWakeSettings parameter. In other words, the framework performs the following steps the first time the driver calls AssignSxWakeSettings but not during later calls:

Stores the value of the UserControlOfWakeSettings parameter.

Looks for a user setting in the registry, if the value of the Enabled parameter is WdfUseDefault.

The following rules apply to the value that you specify for the DxState parameter:

The value cannot be PowerDeviceD0.

If you specify DevicePowerMaximum, the framework uses the value that the kernel-mode driver for the device's bus supplied in the DeviceWake member of its WDF_DEVICE_POWER_CAPABILITIES structure.

You cannot specify a device power state that is lower than the device power state in the DeviceWake member of the kernel-mode bus driver's WDF_DEVICE_POWER_CAPABILITIES structure. (In other words, if the bus driver's DeviceWake value is PowerDeviceD2, your function driver's DxState value cannot be PowerDeviceD3.)