IWDFDevice2::AssignSxWakeSettings method (wudfddi.h)

Article
10/21/2021

[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

HRESULT AssignSxWakeSettings(
  [in] DEVICE_POWER_STATE                    DxState,
  [in] WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parameters

[in] DxState

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.

[in] UserControlOfWakeSettings

A WDF_POWER_POLICY_SX_WAKE_USER_CONTROL-typed enumerator that indicates whether users have the ability to modify the device's wake settings.

[in] Enabled

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.

If waking the system is enabled and the system is about to enter a low-power state, the framework calls the driver's IPowerPolicyCallbackWakeFromSx::OnArmWakeFromSx callback function before the device enters a low-power state.

Return value

AssignSxWakeSettings returns S_OK if the operation succeeds. Otherwise, the method might return one of the following values:

Return code	Description
E_INVALIDARG	The caller specified an invalid value for an input parameter.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	The calling driver is not the device's power policy owner.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	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.)

For information about registry entries that control a device's wake capabilities, see User Control of Device Idle and Wake Behavior in UMDF.

For more information about supporting a device's wake capabilities, see Supporting System Wake-Up in UMDF-based Drivers.

The following code example obtains the IWDFDevice2 interface and then calls AssignSxWakeSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
        hr = pIWDFDevice2->AssignSxWakeSettings(PowerDeviceMaximum,
                                                WakeAllowUserControl,
                                                WdfUseDefault);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll