IoSetCompletionRoutine routine

IoSetCompletionRoutine routine

IoSetCompletionRoutine 例程注册了一个 IoCompletion 例程。这个IoCompletion 例程在下一层级的驱动程序完成在IRP中指定的请求操作时被调用。

Syntax

 

VOID IoSetCompletionRoutine(
  _In_     PIRP                   Irp,
  _In_opt_ PIO_COMPLETION_ROUTINE CompletionRoutine,
  _In_opt_ PVOID                  Context,
  _In_     BOOLEAN                InvokeOnSuccess,
  _In_     BOOLEAN                InvokeOnError,
  _In_     BOOLEAN                InvokeOnCancel
);

 

Parameters

Irp [in]

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

CompletionRoutine [in, optional]

指定一个驱动程序提供的IoCompletion例程，此例程将在下一层驱动完成这个IRP包的请求时被调用。

Context [in, optional]

指向一个驱动决定的上下文以提供给IoCompletion例程。上下文信息必须被储存在非分页内存中，因为IoCompletion 是在IRQL <= DISPATCH_LEVEL.

的IRQL级别中被调用的。

InvokeOnSuccess [in]

指定是否在IRP成功完成时调用这个例程。IRP成功完成是指：使用NT_SUCCESS宏，以IRP的IO_STATUS_BLOCK 结构中的状态值为参数得到的结果。有关更多信息见 Using NTSTATUS values.

InvokeOnError [in]

指定是否在IRP未成功完成时调用这个例程。未成功完成指：在IRP完成时，它的IO_STATUS_BLOCK结构体的状态值为一个“非成功”状态值。

InvokeOnCancel [in]

Specifies whether the completion routine is called if a driver or the kernel has called IoCancelIrp to cancel the IRP.

指定是否在IRP被取消时调用例程。即当一个驱动程序或是内核在这个IRP上调用了IoCancelIrp取消了IRP操作。

Return value

None

Remarks

Note   只有那些可以确保在完成例程结束前不会被卸载的驱动程序可以使用 IoSetCompletionRoutine，否者驱动程序应该使用IoSetCompletionRoutineEx，它可以阻止卸载驱动直到完成例程被执行。

这个例程设定了给定IRP的 IoCompletion 例程的传输地址（ the transfer address of the IoCompletion routine），在分层驱动程序中最底层的驱动程序不可以调用这个例程。（因他们没有下一层驱动）

IoSetCompletionRoutine 注册了一个指定的例程，当下一层驱动以如下任一方式完成了一个请求的操作时注册的例程被调用：

· 

带有成功状态值

· 

带有失败状态值

· 

取消了 IRP

· 

通常情况下I/O status block 被底层的设备驱动程序设置。高层级的驱动程序的 IoCompletion 例程可以读它但不能改变它的值。

使用 IoAllocateIrp or IoBuildAsynchronousFsdRequest创建IRP的高层级驱动在传递这些驱动创建的IRP给IoCallDriver之前必须设置这些InvokeOnXxx 参数为TRUE。当在这些（驱动申请内存创建的）IRP之上执行IoCompletion 例程时, 例程必须释放这些IRP和其他所有为这个IRP申请的资源，例如使用 IoBuildPartialMdl创建的MDL之类的东西。 Such a driver should return STATUS_MORE_PROCESSING_REQUIRED when it calls IoFreeIrp to forestall the I/O manager's completion processing for the driver-allocated IRP.

可能在完成实例调用前即被卸载的Non-PnP驱动程序应当使用IoSetCompletionRoutineEx 代替本函数.

Requirements

Target platform	Desktop
Version	Available starting with Windows 2000.
Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	CompleteRequest, CompleteRequestStatusCheck, CompletionRoutineRegistered, IoAllocateForward,IoAllocateIrpSignalEventInCompletion, IoAllocateIrpSignalEventInCompletion2, IoAllocateIrpSignalEventInCompletion3,IoAllocateIrpSignalEventInCompletionTimeout, IoBuildFsdForward, IoBuildFsdIrpSignalEventInCompletion,IoBuildFsdIrpSignalEventInCompletion2, IoBuildFsdIrpSignalEventInCompletion3,IoBuildFsdIrpSignalEventInCompletionTimeout, IoSetCompletionRoutineNonPnpDriver, LowerDriverReturn, MarkPower,MarkPowerDown, MarkQueryRelations, MarkStartDevice, PendedCompletedRequest, SignalEventInCompletion,SignalEventInCompletion2, SignalEventInCompletion3, StartDeviceWait, StartDeviceWait3,SetCompletionRoutineFromDispatch, IoFreeIrp

See also

IO_STACK_LOCATION

IoAllocateIrp

IoBuildAsynchronousFsdRequest

IRP

IoBuildPartialMdl

IoFreeIrp

IoSetCompletionRoutineEx