IoSetCompletionRoutine 関数 (wdm.h)

[アーティクル]
02/07/2025

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 構造体の非成功状態値で IRP が完了した場合に完了ルーチンを呼び出すかどうかを指定します。

[in] InvokeOnCancel

ドライバーまたはカーネルが IRP を取り消すために IoCancelIrp 呼び出した場合に、完了ルーチンを呼び出すかどうかを指定します。

戻り値

何一つ

備考

完了ルーチンが終了する前にアンロードされないことを保証できるドライバーのみが、IoSetCompletionRoutine 使用できます。それ以外の場合、ドライバーは IoSetCompletionRoutineEx 使用する必要があります。これにより、完了ルーチンが実行されるまでドライバーがアンロードされなくなります。

このルーチンは、指定された IRP の IoCompletion ルーチンの転送アドレスを設定します。階層化されたドライバーのチェーン内の最下位レベルのドライバーは、このルーチンを呼び出すことはできません。

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

成功状態の値を使用する
nonsuccess 状態値を使用する
IRP を取り消す

通常、I/O 状態ブロックは、基になるデバイスドライバーによって設定されます。これは読み取られますが、IoCompletion ルーチン 上位レベルのドライバーによって変更されることはありません。

IoAllocateIrp または IoBuildAsynchronousFsdRequest を使用して IRP を割り当てる上位レベルのドライバーは、ドライバーによって割り当てられた IRP を IoCallDriver に渡す前に、すべての InvokeOnXxx パラメーターを true に設定してこのルーチン呼び出す必要があります。このような IRP で IoCompletion ルーチンを呼び出す場合は、ドライバーが割り当てた IRP と、要求に対してドライバーが設定したその他のリソース (IoBuildPartialMdl の MDLs など) を解放する必要があります。このようなドライバーは、IoFreeIrp を呼び出して、ドライバー割り当て IRP の I/O マネージャーの完了処理をフォレスト化するときに、STATUS_MORE_PROCESSING_REQUIREDを返す必要があります。

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), IoAllocateIrpSignalEventInCompletion2(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)

次の方法で共有

IoSetCompletionRoutine 関数 (wdm.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース