|
|
|
The Power Manager or a device power policy owner sends this IRP to determine whether it can change the system or device power state, typically to go to sleep. A driver must call PoRequestPowerIrp to allocate and send this IRP.
The Power Manager sends this IRP at IRQL = PASSIVE_LEVEL to device stacks that set the DO_POWER_PAGABLE flag in the PDO.
The Power Manager can send the IRP at IRQL = DISPATCH_LEVEL if the DO_POWER_INRUSH flag is set. Such drivers cannot directly or indirectly access any paged code or data.
Parameters.Power.Type specifies the type of power state being set, either SystemPowerState or DevicePowerState.
Parameters.Power.State specifies the power state itself, as follows:
Parameters.Power.ShutdownType specifies additional information about the requested transition. Possible values are enumerators of the POWER_ACTION type.
None.
A driver sets Irp->IoStatus.Status to STATUS_SUCCESS to indicate that the device can enter the requested state. A driver sets any appropriate failure status to indicate that it cannot enter the requested state.
The parameters for IRP_MN_QUERY_POWER are identical to those for IRP_MN_SET_POWER. Rather than notifying drivers of an irrevocable change to the power state, however, IRP_MN_QUERY_POWER queries whether the system or a device can enter a particular power state.
A driver must not change the power state of its device in response to an IRP_MN_QUERY_POWER request.
For each IRP_MN_QUERY_POWER request a driver receives, it must call PoStartNextPowerIrp, as described in Calling PoStartNextPowerIrp.
The Power Manager sends this IRP to ensure that it can change the system power state without disrupting work, such as dropping network connections.
Whenever possible, the Power Manager queries before sending IRP_MN_SET_POWER to request a system sleep state or a normal system shutdown. However, under some critical conditions (such as the user pressing the Power Off button or a battery expiring), the Power Manager might send an IRP_MN_SET_POWER request without first sending a query power request. The Power Manager queries only for sleep states; it never queries before returning to the working state.
When a driver receives a system power query IRP, it should fail the IRP if it cannot support any of the device states that are valid for the queried system state. For more information, see DeviceState. Otherwise, the driver should pass the IRP to the next lower driver. The bus driver completes the IRP.
When a device power policy owner receives a system power query IRP, it should set an IoCompletion routine in the IRP before passing it down. In the IoCompletion routine, it should send an IRP_MN_QUERY_POWER for a device state that is valid for the queried system state. For more information, see Handling a System Query Power IRP in a Device Power Policy Owner.
When the IRP specifies PowerSystemShutdown (S5), the value at Parameters.Power.ShutdownType provides a reason for the shutdown. The ShutdownType tells the driver whether the system is resetting (PowerActionShutdownReset) or powering off indefinitely to reboot later (PowerActionShutdownOff). For drivers of most devices, the difference is inconsequential. However, for certain devices, such as a video streaming device that performs DMA, a driver might opt to power down its device when the system is resetting, thus stopping any ongoing I/O.
On Microsoft® Windows® 2000 and later systems, the value at ShutdownType can also be PowerActionShutdown. In this case, the driver cannot tell what type of shutdown is requested and should therefore proceed as for a reset.
If a driver fails an IRP_MN_QUERY_POWER request for a system power state, the Power Manager typically responds by issuing an IRP_MN_SET_POWER IRP. Usually, this IRP will reaffirm the current system state. However, it is possible that drivers might receive an IRP_MN_SET_POWER to the queried state or to some other intermediate state. Drivers should be prepared to handle these situations.
A device power policy owner sends this IRP to its stack in response to a system IRP_MN_QUERY_POWER request.
If a driver can put its device in the requested device state, it sets IoStatus.Status to STATUS_SUCCESS and passes the IRP down to the next lower driver, and so forth until the IRP reaches the bus driver. If any driver in the stack must fail the IRP, that driver should complete the IRP immediately by calling IoCompleteRequest and returning a failure status. Drivers that fail the IRP do not pass it further down the stack.
By returning STATUS_SUCCESS, the driver guarantees that it will not start any operation that would change its ability to set the requested power state. The driver should queue any IRPs that require such operations until it completes a set-power IRP that returns the device to an acceptable power state.
On Windows 2000 and later systems, when the IRP specifies PowerDeviceD1, PowerDeviceD2, or PowerDeviceD3, the value at Parameters.Power.ShutdownType provides information about the current system power IRP, if a system power IRP is active. In this case, the value at ShutdownType indicates the currently requested system power state, or PowerActionNone if a system request is not outstanding. On Windows 98/Me, this field always contains PowerActionNone when the IRP requests a device power state.