IoSetCompletionRoutineEx 函数 (wdm.h)

项目
03/08/2023

IoSetCompletionRoutineEx 例程注册 IoCompletion 例程，当下一个较低级别的驱动程序完成给定 IRP 的请求操作时调用该例程。

语法

NTSTATUS IoSetCompletionRoutineEx(
  [in]           PDEVICE_OBJECT         DeviceObject,
  [in]           PIRP                   Irp,
  [in]           PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] PVOID                  Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

参数

[in] DeviceObject

指向驱动程序的设备对象的指针。

[in] Irp

指向驱动程序正在处理的 IRP 的指针。

[in] CompletionRoutine

指定驱动程序提供的 IoCompletion 例程的入口点，该例程在下一个较低级别的驱动程序完成数据包时调用。

[in, optional] Context

指向要传递给 IoCompletion 例程的驱动程序确定上下文的指针。上下文信息必须存储在非分页内存中，因为 IoCompletion 例程在 IRQL <= DISPATCH_LEVEL调用。

[in] InvokeOnSuccess

指定在 IRP 的 IO_STATUS_BLOCK 结构中使用成功状态值完成 IRP 时，是否根据NT_SUCCESS宏的结果调用完成例程 (请参阅使用 NTSTATUS 值) 。

[in] InvokeOnError

指定在 IRP 的 IO_STATUS_BLOCK 结构中使用非成功状态值完成 IRP 时，是否调用完成例程。

[in] InvokeOnCancel

指定在驱动程序或内核调用 IoCancelIrp 以取消 IRP 时是否调用完成例程。

返回值

此例程在成功时返回STATUS_SUCCESS;如果可用于操作的内存不足，则返回STATUS_INSUFFICIENT_RESOURCES。

注解

与 IoSetCompletionRoutine 不同， IoSetCompletionRoutineEx 例程返回 NTSTATUS 值。驱动程序必须检查此值，以确定 IoCompletion 例程是否已成功注册。如果 成功注册 IoCompletion 例程， IoSetCompletionRoutineEx 将分配内存，直到 IoCompletion 例程执行为止。驱动程序必须确保其 IoCompletion 例程通过调用 IoCallDriver 执行;否则，内核将泄漏内存。

IoCompletion 例程必须属于拥有 DeviceObject 指向的设备对象的驱动程序。此要求可防止 IoCompletion 例程在返回之前被卸载。

IoSetCompletionRoutineEx 的行为与 IoSetCompletionRoutine 例程相同，只不过：

IoSetCompletionRoutineEx 保证在 IoCompletion 例程运行之前不会卸载非即插即用驱动程序。
IoSetCompletionRoutineEx 是返回 NTSTATUS 值的例程。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	CompleteRequest (wdm) 、 CompleteRequestStatusCheck (wdm) 、 CompletionRoutineRegistered (wdm) 、 HwStorPortProhibitedDDI (storport) 、 IoAllocateForward (wdm) 、 IoAllocateIrpSignalEventInCompletion (wdm) 、 IoAllocateIrpSignalEventInCompletion2 (wdm) 、 IoAllocateIrpSignalEventInCompletion3 (wdm) 、 IoAllocateIrpSignalEventInCompletionTimeout (wdm) ， IoBuildFsdForward (wdm) 、 IoBuildFsdIrpSignalEventInCompletion (wdm) 、 IoBuildFsdIrpSignalEventInCompletion2 (wdm) 、 IoBuildFsdIrpSignalEventInCompletion3 (wdm) 、 IoBuildFsdIrpSignalEventInCompletionTimeout (wdm) ， IoSetCompletionExCompletionExCompleteIrp (wdm) ， IoSetCompletionRoutineExCheck (wdm) ， IoSetCompletionRoutineExCheckDeviceObject (wdm) ， LowerDriverReturn (wdm) 、 MarkPower (wdm) 、 MarkPowerDown (wdm) 、 MarkQueryRelations (wdm) 、 MarkStartDevice (wdm) 、 PendedCompletedRequestEx () wdm) 、 SetCompletionRoutineFromDispatch (kmdf) 、 SignalEventInCompletion (wdm) 、 SignalEventInCompletion2 (wdm) 、 SignalEventInCompletion3 (wdm) ， StartDeviceWait2 (wdm) 、 StartDeviceWait4 (wdm)