Export (0) Print
Expand All

PowerCompletion routine

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 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

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).

See also

DEVICE_OBJECT
IoCompletion
IO_STATUS_BLOCK
IRP_MJ_POWER
IRP_MN_QUERY_POWER
IRP_MN_SET_POWER
IRP_MN_WAIT_WAKE
PoRequestPowerIrp

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft