WdfDeviceWdmAssignPowerFrameworkSettings function (wdfdevice.h)

[Applies to KMDF and UMDF]

The WdfDeviceWdmAssignPowerFrameworkSettings method registers power management framework (PoFx) settings for single-component devices.

Syntax

NTSTATUS WdfDeviceWdmAssignPowerFrameworkSettings(
  [in] WDFDEVICE                     Device,
  [in] PWDF_POWER_FRAMEWORK_SETTINGS PowerFrameworkSettings
);

Parameters

[in] Device

A handle to the framework device object for which PoFx settings are being specified.

[in] PowerFrameworkSettings

A pointer to a WDF_POWER_FRAMEWORK_SETTINGS structure that describes the client driver’s PoFx settings.

Return value

The WdfDeviceWdmAssignPowerFrameworkSettings method returns an NTSTATUS value that indicates success or failure of the operation.

This method also might return other NTSTATUS values.

Remarks

The WdfDeviceWdmAssignPowerFrameworkSettings method applies only to single-component devices.

Before calling this method, the client driver must first successfully call WdfDeviceAssignS0IdleSettings and set the IdleTimeoutType field of the WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure to SystemManagedIdleTimeout or SystemManagedIdleTimeoutWithHint.

A driver must call WdfDeviceWdmAssignPowerFrameworkSettings before or during the first time a device starts. Because a device can start more than once, for example if resource rebalancing occurs, a driver might call this method from within EvtDriverDeviceAdd or EvtDeviceSelfManagedIoInit. The framework calls these functions only once, even if the device is started more than once.

Alternatively, the driver could keep track of whether it has already called WdfDeviceWdmAssignPowerFrameworkSettings, and call it from one of the following callback functions: EvtDevicePrepareHardware, EvtDeviceD0Entry, EvtDeviceD0EntryPostInterruptsEnabled, or EvtDeviceSelfManagedIoRestart.

If your driver calls WdfDeviceWdmAssignPowerFrameworkSettings more than once, the framework generates a verifier error.

The power management framework (PoFx) is available only on Windows 8 and later. When running on an operating system that does not support PoFx, WdfDeviceWdmAssignPowerFrameworkSettings takes no action and returns STATUS_SUCCESS.

For more information, see Supporting Functional Power States and Overview of the Power Management Framework.

Examples

In the following code example, the driver initializes a WDF_POWER_FRAMEWORK_SETTINGS structure by calling the WDF_POWER_FRAMEWORK_SETTINGS_INIT function. The driver then manually sets some of the members of the structure, and then calls WdfDeviceWdmAssignPowerFrameworkSettings.

NTSTATUS status;
WDF_POWER_FRAMEWORK_SETTINGS poFxSettings;

WDF_POWER_FRAMEWORK_SETTINGS_INIT(&poFxSettings);

poFxSettings.EvtDeviceWdmPostPoFxRegisterDevice = 
                        SingleCompWdmEvtDeviceWdmPostPoFxRegisterDevice;
poFxSettings.EvtDeviceWdmPrePoFxUnregisterDevice =
                        SingleCompWdmEvtDeviceWdmPrePoFxUnregisterDevice;

poFxSettings.Component = &component;
poFxSettings.ComponentIdleStateCallback = 
                        SingleCompWdmIdleStateCallback;
poFxSettings.PoFxDeviceContext = (PVOID) Device;
    
status = WdfDeviceWdmAssignPowerFrameworkSettings(Device, &poFxSettings);

Requirements

See also

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice

WDF_POWER_FRAMEWORK_SETTINGS

WDF_POWER_FRAMEWORK_SETTINGS_INIT