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

コールバック ルーチンは、さまざまな IRP にサービスを提供します。 関数コードの一覧については、「解説」を参照してください。

構文

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

パラメーター

[in, out] DeviceObject

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

[in, out] Irp

要求された I/O 操作を記述する IRP 構造体への呼び出し元から提供されるポインター。

戻り値

ルーチンが成功した場合は、STATUS_SUCCESSを返す必要があります。 それ以外の場合は、Ntstatus.h で定義されているエラー状態値のいずれかを返す必要があります。

注釈

すべてのディスパッチ ルーチンの入力パラメーターは、Irp が指す IRP 構造体で指定されます。 追加のパラメーターは、ドライバーの関連付けられた I/O スタックの場所に指定されます。 これは、IO_STACK_LOCATION 構造体によって記述され、 IoGetCurrentIrpStackLocation を呼び出すことによって取得できます。

通常、すべての ディスパッチ ルーチンは IRQL = PASSIVE_LEVELで任意のスレッド コンテキストで実行されますが、例外があります。 詳細については、「 ディスパッチ ルーチンと IRQL」を参照してください。

ディスパッチ ルーチンの詳細については、「ディスパッチ ルーチンの 作成」を参照してください。 IRP の詳細については、「 IRP の処理」を参照してください。

IRP	コールバックの実装について
IRP_MJ_CLEANUP	ドライバーの DispatchCleanup ルーチンには 、XxxDispatchCleanup という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchCleanup ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_CLEANUP] に格納する必要があります。
IRP_MJ_CLOSE	ドライバーの DispatchClose ルーチンには 、XxxDispatchClose という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchClose ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_CLOSE] に格納する必要があります。
IRP_MJ_CREATE	ドライバーの DispatchCreate ルーチンには、 XxxDispatchCreate という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchCreate ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_CREATE] に格納する必要があります。
IRP_MJ_CREATE または IRP_MJ_CLOSE	ドライバーは、個別の DispatchCreate ルーチンと DispatchClose ルーチンではなく、1 つの DispatchCreateClose ルーチンを提供できます。 ドライバーの DispatchCreateClose ルーチンには、 XxxDispatchCreateClose という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchCreateClose ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_CREATE] およびDriverObject-MajorFunction>[IRP_MJ_CLOSE] に格納する必要があります。
IRP_MJ_DEVICE_CONTROL	ドライバーの DispatchDeviceControl ルーチンには、 XxxDispatchDeviceControl という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchDeviceControl ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL] に格納する必要があります。 システムは、I/O コントロール コードのFILE_XXX フラグを使用して、IRP 送信者が IRP をデバイス オブジェクトに送信する権限を持っているかどうかを判断します。 Windows Server 2003 以降のバージョンの Windows 用ドライバーでは、 IoValidateDeviceIoControlAccess ルーチンを使用して 、DispatchDeviceControl 内でより厳密なアクセス チェックを実行できます。
IRP_MJ_FLUSH_BUFFERS	ドライバーの DispatchFlushBuffers ルーチンには 、XxxDispatchFlushBuffers という名前を付ける必要があります。 ここで、Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchFlushBuffers ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS] に格納する必要があります。
IRP_MJ_INTERNAL_DEVICE_CONTROL	ドライバーの DispatchInternalDeviceControl ルーチンには 、XxxDispatchInternalDeviceControl という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchInternalDeviceControl ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL] に格納する必要があります。
IRP_MJ_PNP	ドライバーの DispatchPnP ルーチンには 、XxxDispatchPnP という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchPnP ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_PNP] に格納する必要があります。
IRP_MJ_POWER	ドライバーの DispatchPower ルーチンには 、XxxDispatchPower という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchPower ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_POWER] に格納する必要があります。
IRP_MJ_QUERY_INFORMATION	ドライバーの DispatchQueryInformation ルーチンには 、XxxDispatchQueryInformation という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchQueryInformation ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION] に格納する必要があります。
IRP_MJ_READ	ドライバーの DispatchRead ルーチンには、 XxxDispatchRead という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchRead ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_READ] に格納する必要があります。
IRP_MJ_READ または IRP_MJ_WRITE	ドライバーは、個別の DispatchRead ルーチンと DispatchWrite ルーチンではなく、1 つの DispatchReadWrite ルーチンを提供できます。 ドライバーの DispatchReadWrite ルーチンには 、XxxDispatchReadWrite という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchReadWrite ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_READ] およびDriverObject-MajorFunction>[IRP_MJ_WRITE] に格納する必要があります。
IRP_MJ_SET_INFORMATION	ドライバーの DispatchSetInformation ルーチンには 、XxxDispatchSetInformation という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchSetInformation ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION] に格納する必要があります。
IRP_MJ_SHUTDOWN	ドライバーの DispatchShutdown ルーチンには 、XxxDispatchShutdown という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchShutdown ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN] に格納する必要があります。 さらに、IRP_MJ_SHUTDOWN要求を受信するには、ドライバーは、DispatchShutdown ルーチンをシステムに登録するために、IoRegisterShutdownNotification または IoRegisterLastChanceShutdownNotification を呼び出す必要があります。
IRP_MJ_SYSTEM_CONTROL	ドライバーの DispatchSystemControl ルーチンには 、XxxDispatchSystemControl という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchSystemControl ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL] に格納する必要があります。
IRP_MJ_WRITE	ドライバーの DispatchWrite ルーチンには 、XxxDispatchWrite という名前を付ける必要があります。 Xxx はドライバー固有のプレフィックスです。 ドライバーの DriverEntry ルーチンは、DispatchWrite ルーチンのアドレスを DriverObject-MajorFunction>[IRP_MJ_WRITE] に格納する必要があります。

例

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

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

DRIVER_DISPATCH MyDispatchCleanup;

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

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

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

要件

要件	値
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	PASSIVE_LEVELで呼び出されます (「解説」セクションを参照)。