IoSetCompletionRoutineEx 関数 (wdm.h)

[アーティクル]
03/08/2023

IoSetCompletionRoutineEx ルーチンは、次の下位レベルのドライバーが指定された IRP に対して要求された操作を完了したときに呼び出される IoCompletion ルーチンを登録します。

構文

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 の IO_STATUS_BLOCK 構造体の成功状態値で IRP が完了した場合に完了ルーチンを呼び出すかどうかを指定します ( 「NTSTATUS 値の使用」を参照)。

[in] InvokeOnError

IRP が IRP の IO_STATUS_BLOCK 構造体で非success 状態値で完了した場合に、完了ルーチンを呼び出すかどうかを指定します。

[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 値を返すルーチンです。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	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)