PoRequestPowerIrp

The PoRequestPowerIrp routine allocates a power IRP and sends it to the top driver in the device stack for the specified device.

NTSTATUS
  PoRequestPowerIrp(
    IN PDEVICE_OBJECT  DeviceObject,
    IN UCHAR  MinorFunction,
    IN POWER_STATE  PowerState,
    IN PREQUEST_POWER_COMPLETE  CompletionFunction,
    IN PVOID  Context,
    OUT PIRP  *Irp OPTIONAL
    );

Parameters

DeviceObject

Pointer to the target DEVICE_OBJECT for the IRP. On Windows 2000 and later systems, this parameter can point to a physical device object (PDO) or a functional device object (FDO). On Windows 98/Me, this parameter must point to the PDO of the underlying device.

MinorFunction

Specifies one of the following minor power IRP codes: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER, or IRP_MN_WAIT_WAKE.

PowerState

Specifies a power state to pass in the IRP. For IRP_MN_SET_POWER and IRP_MN_QUERY_POWER, specify the requested new device power state. Possible values are DEVICE_POWER_STATE enumerator values.

For IRP_MN_WAIT_WAKE, specify the lowest (least-powered) system power state from which the device should be allowed to wake the system Possible values are SYSTEM_POWER_STATE enumerator values.

CompletionFunction

Pointer to the caller's PowerCompletion callback to be called when the IRP has completed. The callback is declared as follows:

VOID
(*PREQUEST_POWER_COMPLETE) (
    IN PDEVICE_OBJECT DeviceObject,
    IN UCHAR MinorFunction,
    IN POWER_STATE PowerState,
    IN PVOID Context,
    IN PIO_STATUS_BLOCK IoStatus
    );

The callback parameters are as follows:

DeviceObject

Pointer to the target device object for the completed power IRP.

MinorFunction

Specifies the minor function code in the power IRP.

PowerState

Specifies the device power state passed to PoRequestPowerIrp.

Context

Pointer to the context passed to PoRequestPowerIrp.

IoStatus

Pointer to the IO_STATUS_BLOCK structure for the completed IRP.

Context

Pointer to a caller-supplied context to be passed through to the PowerCompletion callback. When the caller requests a device set-power IRP in response to a system set-power IRP, the Context should contain the system set-power IRP that triggered the request.

Irp

Pointer to a caller-supplied variable in which this routine returns a pointer to the IRP it allocates. This parameter can be NULL.

Return Value

PoRequestPowerIrp returns one of the following:

STATUS_PENDING

The IRP has been sent.

STATUS_INSUFFICIENT_RESOURCES

The routine could not allocate the IRP.

STATUS_INVALID_PARAMETER_2

MinorFunction does not signify a valid minor power IRP code.

Headers

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

Comments

A driver calls PoRequestPowerIrp — not IoAllocateIrp — to allocate and send a power IRP that has minor IRP code IRP_MN_SET_POWER, IRP_MN_QUERY_POWER, or IRP_MN_WAIT_WAKE. (A driver must call IoAllocateIrp to send a power IRP with minor IRP code IRP_MN_POWER_SEQUENCE.)

A device power policy owner calls this routine to send a wait/wake, query, or set-power IRP.

If PoRequestPowerIrp returns a status value of STATUS_PENDING, the routine successfully allocated a device power IRP and sent it to the top of the device stack for the device. After the bus driver and all other drivers have completed the IRP, and the I/O Manager has called all IoCompletion routines set by drivers as they passed the IRP down the device stack, the CompletionFunction is called with the given Context. If PoRequestPowerIrp returns a status other than STATUS_PENDING, the routine did not send a device power IRP and the CompletionFunction is not called.

The CompletionFunction performs any additional tasks the sender of the IRP requires after all other drivers have completed the IRP. It need not free the IRP; the Power Manager does that. On Windows 98/Me, the CompletionFunction is always called at IRQL = PASSIVE_LEVEL, and drivers must complete IRPs at IRQL = PASSIVE_LEVEL. On Windows 2000 and later systems, the CompletionFunction can be called at IRQL = PASSIVE_LEVEL or IRQL = DISPATCH_LEVEL.

A device power policy owner calls PoRequestPowerIrp to send a device query- or set-power IRP when it receives a system query- or set-power IRP. The driver should set an IoCompletion routine in the system IRP and pass the system IRP to the next lower driver. The IoCompletion routine calls PoRequestPowerIrp to send the device IRP, passing the system IRP in the Context parameter. The Context parameter is subsequently passed to the CompletionFunction for the device IRP. In the CompletionFunction, the driver can complete the system IRP. For more information, see Sending IRP_MN_QUERY_POWER or IRP_MN_SET_POWER for Device Power States and Wait/Wake Callback Routines.

Drivers can use the returned Irp to cancel an IRP_MN_WAIT_WAKE IRP. Drivers requesting other power IRPs can pass NULL for this parameter.

Callers of PoRequestPowerIrp must be running at IRQL <= DISPATCH_LEVEL.

See Also

IoAllocateIrp, IO_STATUS_BLOCK, IRP, PoStartNextPowerIrp, IRP_MN_POWER_SEQUENCE, IRP_MN_SET_POWER, IRP_MN_QUERY_POWER, IRP_MN_WAIT_WAKE