IoSetCompletionRoutine 函式 (wdm.h)

發行項
03/05/2024

IoSetCompletionRoutine 例程會註冊 IoCompletion 例程，當下一個較低層級驅動程式已完成指定 IRP 的要求作業時，將會呼叫此例程。

語法

void IoSetCompletionRoutine(
  [in]           PIRP                   Irp,
  [in, optional] PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] __drv_aliasesMem PVOID Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

參數

[in] Irp

驅動程式正在處理的 IRP 指標。

[in, optional] 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，則會呼叫完成例程。

傳回值

無

備註

只有在完成例程完成後，才能保證不會卸除的驅動程式可以使用 IoSetCompletionRoutine。否則，驅動程式必須使用 IoSetCompletionRoutineEx，以防止驅動程式卸除，直到完成例程執行為止。

此例程會在指定的 IRP 中設定 IoCompletion 例程的傳輸位址。分層驅動程式鏈結中的最低層級驅動程式無法呼叫此例程。

IoSetCompletionRoutine 會在下一個較低層級的驅動程式以下列任何或所有方式完成要求的作業時，註冊要呼叫的指定例程：

成功狀態值
具有 Nonsuccess 狀態值
取消 IRP

I/O 狀態區塊通常是由基礎設備驅動器所設定。它會讀取，但不會由任何較高層級驅動程式的 IoCompletion 例程改變。

使用 IoAllocateIrp 或 IoBuildAsynchronousFsdRequest 配置 IRP 的高階驅動程式，必須先呼叫此例程，並將所有 InvokeOnXxx 參數設定為 TRUE ，再將驅動程式配置的 IRP 傳遞至 IoCallDriver。使用這類 IRP 呼叫 IoCompletion 例程時，它必須釋放驅動程式配置的 IRP，以及驅動程式為要求設定的任何其他資源，例如搭配 IoBuildPartialMdl 的 MDL。這類驅動程式應該會在呼叫 IoFreeIrp 時傳回STATUS_MORE_PROCESSING_REQUIRED，以樹系處理驅動程式配置的I/O管理員完成處理。

在 IoCompletion 例程執行之前可能卸除的非 PnP 驅動程式應該改用 IoSetCompletionRoutineEx 。

規格需求

需求	值
目標平台	桌面
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL	IRQL <= DISPATCH_LEVEL
DDI 合規性規則	CompleteRequest (wdm) 、 CompleteRequestStatusCheck (wdm ) 、 CompletionRoutineRegistered (wdm) 、 IoAllocateForward (wdm) 、 IoAllocateIrpSignalEventInCompletion (wdm ) 、 IoAllocateIr pSignalEventInCompletion2 (wdm) 、 IoAllocateIrpSignalEventInCompletion3 (wdm) 、 IoAllocateIrpSignalEventInCompletionTimeout (wdm ) 、 IoBuildFsdForward (wdm) 、 IoBuildFsdIrpSignalEventInCompletion (wdm) 、 IoBuildFsdIrpSignalEventInCompletion2 (wdm) 、 IoBuildFsdIrpSignalEventInCompletion3 (wdm) 、 IoBuildFsdIrpSignalEventInCompletionTimeout (wdm) 、 IoFreeIrp (storport) 、 IoSetCompletionRoutineNonPnpDriver (wdm ) 、 LowerDriverReturn (wdm) 、 MarkPower (wdm ) 、 MarkPowerDown (wdm) 、 MarkQueryRelations (wdm) 、 MarkStartDevice (wdm) 、 PendedCompletedRequest (wdm) 、 SetCompletionRoutineFromDispatch (kmdf) 、 SignalEventInCompletion (wdm) 、 SignalEventInCompletion2 (wdm) 、 SignalEventInCompletion3 (wdm) 、 StartDeviceWait (wdm) 、 StartDeviceWait3 (wdm)