WdfDeviceAssignSxWakeSettings function (wdfdevice.h)

Article
02/22/2024

[Applies to KMDF and UMDF]

The WdfDeviceAssignSxWakeSettings 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

NTSTATUS WdfDeviceAssignSxWakeSettings(
  [in] WDFDEVICE                              Device,
  [in] PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Settings
);

Parameters

[in] Device

A handle to a framework device object.

[in] Settings

A pointer to a caller-supplied WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure.

Return value

If the operation succeeds, WdfDeviceAssignSxWakeSettings returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	The calling driver is not the device's power policy owner.
STATUS_INVALID_PARAMETER	An invalid Settings value is detected.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure is incorrect.
STATUS_POWER_STATE_INVALID	The bus driver indicates the device cannot trigger a wake signal, or the WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure contains an invalid device power state.

The method might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

For more information, see Supporting System Wake-Up.

Examples

The following code example initializes a WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure and then calls WdfDeviceAssignSxWakeSettings. The example uses the default settings that WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT sets.

WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS  wakeSettings;
NTSTATUS  status = STATUS_SUCCESS;

WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT(&wakeSettings);

status = WdfDeviceAssignSxWakeSettings(
                                       device,
                                       &wakeSettings
                                       );
if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfdevice.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), FDOPowerPolicyOwnerAPI(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NonFDONotPowerPolicyOwnerAPI(kmdf)