IoSetCompletionRoutineEx 函式 (wdm.h)

發行項
02/29/2024

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)