REQUEST_POWER_COMPLETE callback function (wdm.h)

Article
02/28/2023

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

Syntax

REQUEST_POWER_COMPLETE RequestPowerComplete;

void RequestPowerComplete(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in]           UCHAR MinorFunction,
  [in]           POWER_STATE PowerState,
  [in, optional] PVOID Context,
  [in]           PIO_STATUS_BLOCK IoStatus
)
{...}

Parameters

[in] DeviceObject

A pointer to the target DEVICE_OBJECT for the completed power IRP.

[in] MinorFunction

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.

[in] PowerState

Specifies the device power state or system power state that was passed to the PoRequestPowerIrp routine.

[in, optional] Context

A pointer to the context that was passed to PoRequestPowerIrp.

[in] IoStatus

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.

The PowerCompletion routine is called at IRQL = PASSIVE_LEVEL or IRQL = DISPATCH_LEVEL.

Examples

To define a PowerCompletion callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a PowerCompletion callback routine that is named MyPowerCompletion, use the REQUEST_POWER_COMPLETE type as shown in this code example:

REQUEST_POWER_COMPLETE MyPowerCompletion;

Then, implement your callback routine as follows:

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

The REQUEST_POWER_COMPLETE function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the REQUEST_POWER_COMPLETE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Requirement	Value
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Called at IRQL <= DISPATCH_LEVEL (see Remarks section).