PoSetPowerState

The PoSetPowerState routine notifies the system of a change in the device power state for a device.

POWER_STATE
  PoSetPowerState(
    IN PDEVICE_OBJECT  DeviceObject,
    IN POWER_STATE_TYPE  Type,
    IN POWER_STATE  State
    );

Parameters

DeviceObject

Pointer to the target DEVICE_OBJECT.

Type

Indicates whether to set a system power state or a device power state. Drivers must specify DevicePowerState.

State

Specifies the power state to be set. Drivers must specify an enumerator of DEVICE_POWER_STATE: PowerDeviceD0, PowerDeviceD1, PowerDeviceD2, or PowerDeviceD3.

Return Value

On Windows 2000 and later versions of the operating system, PoSetPowerState returns the previous power state. On Windows 98/Me, PoSetPowerState returns the state passed in State.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

PoSetPowerState notifies the Power Manager of the new power state for a device. Each driver in a device stack (filter, function, and bus drivers) must call PoSetPowerState to inform the Power Manager of a change in the power state of its corresponding device object. For example:

• A driver calls this routine after receiving a device set-power request and before calling PoStartNextPowerIrp. When handling a PnP IRP_MN_START_DEVICE request, the driver should call PoSetPowerState to notify the Power Manager that the device is in the D0 state.
• If the device is powering down, the driver must call PoSetPowerState before leaving the D0 state. In addition, the driver must be able to process client requests before PoSetPowerState returns.
• If the device is powering up, the driver must call PoSetPowerState after the device is successfully put into the D0 state.

For more information about powering a device up and down, see Handling IRP_MN_SET_POWER for Device Power States.

Callers of PoSetPowerState must be running at IRQL < DISPATCH_LEVEL except when setting state to D0. When setting state to D0, callers can be running at IRQL <= DISPATCH_LEVEL.

See Also

IRP_MN_START_DEVICE, PoStartNextPowerIrp