KDEFERRED_ROUTINE回调函数 (wdm.h)

项目
03/08/2023

回调例程在 InterruptService 返回后执行线程 DPC 的操作，

在 InterruptService 例程返回后，CustomDpc 例程完成 I/O 操作的服务。

CustomThreadedDpc 例程执行线程 DPC 的操作。当线程 DPC 运行时，系统会执行此例程。

CustomTimerDpc 例程在计时器对象的时间间隔到期后执行。

语法

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

参数

[in] Dpc

调用方提供的指向 KDPC 结构的指针，该结构表示与此回调例程关联的 DPC 对象。

[in, optional] DeferredContext

对于 CustomDpc，是调用方提供的指向驱动程序定义的上下文信息的指针，该信息是在之前对 KeInitializeDpc 的调用中指定的。

对于 CustomThreadedDpc，指定驱动程序定义的上下文信息。初始化 DPC 对象时，驱动程序将此值作为 DeferredContext 参数提供给 KeInitializeThreadedDpc。

调用方提供的指向 KDPC 结构的指针，该结构表示与此 CustomTimerDpc 例程关联的 DPC 对象。

[in, optional] SystemArgument1

调用方提供的指向驱动程序提供的信息的指针，该信息是在对 KeInsertQueueDpc 的上一次调用中指定的。将 DPC 添加到 DPC 队列时，驱动程序将此值作为 SystemArgument1 参数提供给 KeInsertQueueDpc。

对于 CustomTimerDpc，不使用此值。

[in, optional] SystemArgument2

指定驱动程序定义的上下文信息。将 DPC 添加到 DPC 队列时，驱动程序将此值作为 SystemArgument2 参数提供给 KeInsertQueueDpc。

对于 CustomTimerDpc，不使用此值。

返回值

无

备注

若要创建 DPC 对象并为该对象注册 CustomDpc 例程，驱动程序必须调用 KeInitializeDpc。 (如果只需要一个 DPC 例程，则可以使用 DpcForIsr 例程和系统分配的 DPC 对象.)

若要将 CustomDpc 例程排队以供执行，驱动程序的 InterruptService 例程必须调用 KeInsertQueueDpc。

一个或多个 CustomDpc 例程可以代替 DpcForIsr 例程，也可以与 DpcForIsr 例程结合使用。维护多个内部 IRP 队列的驱动程序通常为每个队列提供 CustomDpc 例程。每个 CustomDpc 例程通常至少负责以下任务：

完成当前 IRP 描述的 I/O 操作。
从驱动程序的某个 IRP 队列中取消下一个 IRP 排队。 (使用系统提供的 IRP 队列和 StartIo 例程的驱动程序调用 IoStartNextPacket.)
在当前 IRP 中设置 I/O 状态块，并为已完成的请求调用 IoCompleteRequest 。

CustomDpc 例程可能还会重试失败的操作，或者为已拆分为小块的大型 I/O 请求设置下一次传输。

有关 CustomDpc 例程的详细信息，请参阅 DPC 对象和 DPC。

驱动程序通过调用 KeInitializeThreadedDpc 为 DPC 对象注册 CustomThreadedDpc。若要实际将 DPC 添加到 DPC 队列，以便执行 CustomThreadedDpc 例程，请调用 KeInsertQueueDpc。

有关使用 CustomThreadedDpc 例程的详细信息，请参阅线程 DPC 简介。

CustomThreadedDpc 例程可以在 IRQL = DISPATCH_LEVEL 运行，也可以在实时线程中的 IRQL = PASSIVE_LEVEL 运行。

若要创建 DPC 对象并为该对象注册 CustomTimerDpc 例程，驱动程序必须调用 KeInitializeDpc。

若要将 CustomTimerDpc 例程排队以供执行，驱动程序例程必须调用 KeSetTimer 或 KeSetTimerEx，并提供 KeInitializeDpc 返回的 DPC 对象指针。当计时器间隔过期时，系统会调用 CustomTimerDpc 例程。

有关 CustomTimerDpc 例程的详细信息，请参阅计时器对象和 DPC。

示例

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

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

KDEFERRED_ROUTINE MyCustomDpc;

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

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }