IoSetCompletionRoutineEx 函式 （wdm.h）

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 例程之驅動程式決定內容的指標。 內容信息必須儲存在非分頁記憶體中，因為會在 IRQL <= DISPATCH_LEVEL呼叫 IoCompletion 例程。

[in] InvokeOnSuccess

指定是否根據NT_SUCCESS巨集的結果，以 IRP IO_STATUS_BLOCK 結構的成功狀態值完成 IRP 時呼叫完成例程（請參閱使用 NTSTATUS 值 ）。

[in] InvokeOnError

指定是否在 IRP 的 IO_STATUS_BLOCK 結構中，以非uccess 狀態值完成 IRP 時呼叫完成例程。

[in] InvokeOnCancel

指定驅動程式或核心是否已呼叫 IoCancelIrp 取消 IRP 時呼叫完成例程。

傳回值

此例程會在成功時傳回STATUS_SUCCESS，如果作業的記憶體不足，則傳回STATUS_INSUFFICIENT_RESOURCES。

言論

不同於 ioSetCompletionRoutine ，IoSetCompletionRoutineEx 例程會傳回 NTSTATUS 值。 驅動程式必須檢查此值，以判斷是否已成功註冊 IoCompletion 例程。 如果成功註冊 IoCompletion 例程，IoSetCompletionRoutineEx 配置仍會配置記憶體，直到 IoCompletion 例程執行為止。 驅動程式必須藉由呼叫ioCallDriver ，確保其 IoCompletion 例程執行;否則，核心將會流失記憶體。

IoCompletion 例程必須屬於擁有 deviceObject 所指向之裝置對象的驅動程式。 這項需求可防止 IoCompletion 例程在傳回之前卸除。

IoSetCompletionRoutineEx 的行為與 IoSetCompletionRoutine 例程相同，不同之處在於：

  • IoSetCompletionRoutineEx 保證在 IoCompletion 例程執行之前，不會卸除非即插即用驅動程式。

  • IoSetCompletionRoutineEx 是傳回 NTSTATUS 值的例程。

要求

要求 價值
目標平臺 普遍
標頭 wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL
DDI 合規性規則 CompleteRequest（wdm）、CompleteRequestStatusCheck（wdm）、CompletionRoutineRegistered（wdm）、HwStorPortProhibitedDIS（storport），IoAllocateForward（wdm），IoAllocateIrpSignalEventInCompletion（wdm）、IoAllocateIrpSignalEventInCompletion2（wdm）、IoAllocateIrpSignalEventInCompletion3（wdm）、IoAllocateIrpSignalEventInCompletionTimeout（wdm）、IoBuildFsdForward（wdm）、IoBuildFsdIrpSignalEventInCompletion（wdm）、IoBuildFsdIrpSignalEventInCompletion2（wdm）、IoBuildFsdIr、 IoBuildFsdIrpSignalEventInCompletionTimeout（wdm）、IoSetCompletionExCompleteIrp（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）

另請參閱

IO_STACK_LOCATION

IRP

IoAllocateIrp

IoBuildAsynchronousFsdRequest

IoBuildPartialMdl

IoCompletion

IoFreeIrp

IoSetCompletionRoutine

  • Last updated on