REQUEST_POWER_COMPLETE回调函数 (wdm.h)

项目
02/29/2024

PowerCompletion 回调例程完成电源 IRP 的处理。

语法

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

参数

[in] DeviceObject

指向已完成电源 IRP 的目标 DEVICE_OBJECT 的指针。

[in] MinorFunction

指定电源 IRP 中的次要函数代码。有关详细信息，请参阅“备注”部分中支持的 IRP_MN_XXX 代码列表。

[in] PowerState

指定传递给 PoRequestPowerIrp 例程的设备电源状态或系统电源状态。

[in, optional] Context

指向传递给 PoRequestPowerIrp 的上下文的指针。

[in] IoStatus

指向已完成 IRP 的IO_STATUS_BLOCK 结构的指针。

返回值

无

备注

发送电源 IRP 的驱动程序可能需要在所有其他驱动程序完成 IRP 后执行其他任务。如果是这样，发送驱动程序应在调用分配 IRP 的 PoRequestPowerIrp 例程期间注册 PowerCompletion 回调例程。

驱动程序的 PowerCompletion 回调例程仅用于 IRP_MJ_POWER IRP 代码为 IRP_MN_SET_POWER、 IRP_MN_QUERY_POWER和 IRP_MN_WAIT_WAKE的 IRP。有关详细信息，请参阅为设备电源状态发送IRP_MN_QUERY_POWER或IRP_MN_SET_POWER 和等待/唤醒回调例程。

I/O 管理器仅在 I/O 管理器调用其他驱动程序在将 IRP 向下传递 IRP 时设置的所有 IoCompletion 例程之后，才调用发送驱动程序的 PowerCompletion 例程。在所有其他驱动程序完成 IRP 后， PowerCompletion 例程执行 IRP 发送方要求的任何其他任务。 PowerCompletion 例程不应释放 IRP，电源管理器会这样做。

在 IRQL = PASSIVE_LEVEL 或 IRQL = DISPATCH_LEVEL 调用 PowerCompletion 例程。

示例

若要定义 PowerCompletion 回调例程，必须首先提供一个函数声明，用于标识要定义的回调例程的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

例如，若要定义名为 MyPowerCompletion的 PowerCompletion 回调例程，请使用REQUEST_POWER_COMPLETE类型，如以下代码示例所示：

REQUEST_POWER_COMPLETE MyPowerCompletion;

然后，按如下所示实现回调例程：

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

REQUEST_POWER_COMPLETE函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。注释 _Use_decl_annotations_ 可确保使用应用于头文件中REQUEST_POWER_COMPLETE函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关的信息 _Use_decl_annotations_，请参阅批注函数行为。