PowerCompletion

Article
06/05/2010

The PowerCompletion callback routine completes the processing of a power IRP.

Syntax

REQUEST_POWER_COMPLETE PowerCompletion;

VOID PowerCompletion(
  __in      PDEVICE_OBJECT DeviceObject,
  __in      UCHAR MinorFunction,
  __in      POWER_STATE PowerState,
  __in_opt  PVOID Context,
  __in      PIO_STATUS_BLOCK IoStatus
)
{ ... }

Parameters

DeviceObject [in]
A pointer to the target DEVICE_OBJECT for the completed power IRP.
MinorFunction [in]
Specifies the minor function code in the power IRP. For more information, see the list of supported IRP_MN_XXX codes in the Remarks section.
PowerState [in]
Specifies the device power state or system power state that was passed to the PoRequestPowerIrp routine.
Context [in, optional]
A pointer to the context that was passed to PoRequestPowerIrp.
IoStatus [in]
A pointer to the IO_STATUS_BLOCK structure for the completed IRP.

Return Value

None

Remarks

A driver that sends a power IRP might need to perform additional tasks after all other drivers have completed the IRP. If so, the sending driver should register a PowerCompletion callback routine during the call to the PoRequestPowerIrp routine that allocates the IRP.

A driver's PowerCompletion callback routine is used only for IRP_MJ_POWER IRPs that have minor IRP codes of IRP_MN_SET_POWER, IRP_MN_QUERY_POWER, and IRP_MN_WAIT_WAKE. For more information, see Sending IRP_MN_QUERY_POWER or IRP_MN_SET_POWER for Device Power States and Wait/Wake Callback Routines.

The I/O manager calls the sending driver's PowerCompletion routine only after the I/O manager has called all the IoCompletion routines that were set by other drivers as they passed the IRP down the stack. The PowerCompletion routine performs any additional tasks that the sender of the IRP requires after all other drivers have completed the IRP. The PowerCompletion routine should not free the IRP—the power manager does that.

In Windows 2000 and later versions of Windows, the PowerCompletion routine is called at IRQL = PASSIVE_LEVEL or IRQL = DISPATCH_LEVEL. In Windows 98/Me, the PowerCompletion routine is always called at IRQL = PASSIVE_LEVEL, and drivers must complete IRPs at IRQL = PASSIVE_LEVEL.

Examples

To define a PowerCompletion routine that is named MyPowerCompletion, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as shown in the following code example:

REQUEST_POWER_COMPLETE MyPowerCompletion;

Then, implement your callback routine as follows:

VOID MyPowerCompletion(
    __in PDEVICE_OBJECT DeviceObject,
    __in UCHAR MinorFunction,
    __in POWER_STATE PowerState,
    __in_opt PVOID Context,
    __in PIO_STATUS_BLOCK IoStatus
    )
  {
      // Function body
  }

The REQUEST_POWER_COMPLETE function type is defined in the Wdm.h header file. For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for WDM Drivers.

Requirements

Version	Supported in Windows 2000 and later versions of Windows.
Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
IRQL	Called at IRQL <= DISPATCH_LEVEL (see Remarks section).