IO_COMPLETION_ROUTINE コールバック関数 (wdm.h)

2025-02-07

IoCompletion ルーチンは、I/O 操作の処理を完了します。

構文

IO_COMPLETION_ROUTINE IoCompletionRoutine;

NTSTATUS IoCompletionRoutine(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in]           PIRP Irp,
  [in, optional] PVOID Context
)
{...}

パラメーター

[in] DeviceObject

呼び出し元が指定した DEVICE_OBJECT 構造体へのポインター。これは、以前にドライバーの AddDevice ルーチンによって作成されたターゲットデバイスのデバイスオブジェクトです。

[in] Irp

I/O 操作を記述する IRP 構造体への呼び出し元が指定したポインター。

[in, optional] Context

IoSetCompletionRoutine または IoSetCompletionRoutineEx を呼び出すとき以前に指定した、ドライバー固有のコンテキスト情報への呼び出し元指定ポインター。 IoCompletion ルーチンはDISPATCH_LEVELで呼び出すことができるため、コンテキスト情報は非ページメモリに格納する必要があります。詳細については、次の「解説」セクションを参照してください。

戻り値

IoCompletion ルーチンが IRP に追加の処理が必要であると判断した場合は、STATUS_MORE_PROCESSING_REQUIREDを返す必要があります。詳細については、次の「解説」セクションを参照してください。それ以外の場合は、STATUS_SUCCESSを返す必要があります。 (I/O マネージャーは、STATUS_MORE_PROCESSING_REQUIREDの有無のみを確認します。

備考

ドライバーの IoCompletion ルーチンは、任意のスレッドまたは DPC コンテキスト、およびDISPATCH_LEVEL以下の IRQL で実行されます。 DISPATCH_LEVELで実行するように記述されたコードも下位レベルで実行されるため、IoCompletion ルーチン DISPATCH_LEVELで実行するように設計する必要があります。ただし、これらのルーチンはDISPATCH_LEVELで実行することが保証されていないため、DISPATCH_LEVELで実際に実行を必要とするシステムルーチンを呼び出してはなりません。 (IRQL の詳細については、「ハードウェア優先度の管理」を参照してください)。

特定の IRP の IoCompletion ルーチンを登録するには、ドライバーが IoSetCompletionRoutine 呼び出すか、IoSetCompletionRoutineEx を呼び出す必要があります。これは、IoCompletion ルーチンのアドレスを次の下位ドライバーの I/O スタックの場所に格納します。 (したがって、最下位レベルのドライバーは、IoCompletion ルーチンを登録できません。ドライバーは通常、IRP を受信するたびに、IoSetCompletionRoutine または IoSetCompletionRoutineEx をディスパッチルーチンの 1 つから呼び出します。すべての PnP ドライバーを含むほとんどのドライバーは、IoSetCompletionRoutine を使用して、IoCompletion ルーチンを登録できます。 IoCompletion ルーチンが実行される前にアンロードされる可能性がある非 PnP ドライバーは、代わりに IoSetCompletionRoutineEx 使用する必要があります。

ドライバーが IRP を完了すると、IoCompleteRequestを呼び出します。この呼び出しは、次に高いレベルの各ドライバーの IoCompletion ルーチンを呼び出します。次に高いレベルから高いレベルまで、IoCompletion のすべての上位 ルーチンが呼び出されるまで、または 1 つのルーチンがSTATUS_MORE_PROCESSING_REQUIREDを返すまで呼び出されます。

IRP を作成するときに、現在のドライバーと下位ドライバーのスタックの場所を割り当てます。十分なスタック位置を割り当てない場合は、完了ルーチンが呼び出されたときに、DeviceObject ポインターが NULL をするように設定されている可能性があります。 DeviceObject パラメーターに依存するのではなく、コンテキスト フィールドを使用して IoCompletion に情報を渡す場合は、現在のドライバーに追加のスタック位置を割り当てないようにすることができます。

IoCompletion ルーチンがSTATUS_MORE_PROCESSING_REQUIREDを返す場合、下位のドライバーが IoCompleteRequest を呼び出すとすぐに戻ります。この場合、上位レベルのドライバーは、IoCompleteRequest を呼び出して IRP を完了する必要があります。

IoCompletion ルーチンの実装の詳細については、「IRPの完了」を参照してください。

例

IoCompletion コールバックルーチンを定義するには、まず、定義するコールバックルーチンの型を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。コールバック関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールをすると、エラーが検出され、Windows オペレーティングシステムのドライバーを記述するための要件になります。

たとえば、MyIoCompletionという名前の IoCompletion コールバックルーチンを定義するには、次のコード例に示すようにIO_COMPLETION_ROUTINE型を使用します。

IO_COMPLETION_ROUTINE MyIoCompletion;

次に、次のようにコールバックルーチンを実装します。

_Use_decl_annotations_
NTSTATUS
  MyIoCompletion(
    PDEVICE_OBJECT  DeviceObject,
    PIRP  Irp,
    PVOID  Context
    )
  {
      // Function body
  }

IO_COMPLETION_ROUTINE関数の種類は、Wdm.h ヘッダーファイルで定義されています。コード分析ツールの実行時にエラーをより正確に識別するには、_Use_decl_annotations_ 注釈を関数定義に追加してください。 _Use_decl_annotations_ 注釈により、ヘッダーファイル内のIO_COMPLETION_ROUTINE関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「WDM ドライバーのの関数の役割の種類を使用して関数を宣言するを参照してください。 _Use_decl_annotations_の詳細については、「関数の動作に注釈を付けるを参照してください。

必要条件

要件	価値
ターゲットプラットフォームの	デスクトップ
ヘッダー	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	IRQL <= DISPATCH_LEVEL で呼び出されます (「解説」セクションを参照)。

次の方法で共有

IO_COMPLETION_ROUTINE コールバック関数 (wdm.h)

構文

パラメーター

戻り値

備考

例

必要条件

フィードバック

その他のリソース