IoSetCompletionRoutineEx 関数 (wdm.h)
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 値を返すルーチンです。