共用方式為


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

[in] InvokeOnSuccess

根據NT_SUCCESS宏的結果,指定是否呼叫完成例程,如果 IRP 在 IRP 的 IO_STATUS_BLOCK 結構中使用成功狀態值, (請參閱 使用 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 值的例程。

規格需求

需求
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL <= DISPATCH_LEVEL
DDI 合規性規則 CompleteRequest (wdm) CompleteRequestStatusCheck (wdm) CompletionRoutineRegistered (wdm) HwStorPortProhibitedDDIs (storport) IoAllocateForward (wdm) IoAllocateIrpSignalEventInCompletion (wdm) IoAllocateIrpSignalEventInCompletion2 (wdm) IoAllocateIrpSignalEventInCompletion3 (wdm) IoAllocateIrpSignalEventInCompletionTimeout (wdm) IoBuildFsdForward (wdm) IoBuildFsdIrpSignalEventInCompletion (wdm) IoBuildFsdIrpSignalEventInCompletion2 (wdm) IoBuildFsdIrpSignalEventInCompletion3 (wdm) 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