DRIVER_OBJECT 構造体 (wdm.h)

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

各ドライバーオブジェクトは、読み込まれたカーネルモードドライバーのイメージを表します。ドライバーオブジェクトへのポインターは、ドライバーの DriverEntry、 AddDevice、および省略可能な再初期化ルーチンへの入力パラメーターであり、存在する場合は Unload ルーチンに対する入力パラメーターです。

ドライバーオブジェクトが部分的に不透明です。ドライバーのライターは、ドライバーを初期化し、ドライバーがアンロード可能な場合、それをアンロードするドライバーオブジェクトの特定のメンバーについて知っている必要があります。ドライバーオブジェクトの次のメンバーは、ドライバーからアクセスできます。

構文

typedef struct _DRIVER_OBJECT {
  CSHORT             Type;
  CSHORT             Size;
  PDEVICE_OBJECT     DeviceObject;
  ULONG              Flags;
  PVOID              DriverStart;
  ULONG              DriverSize;
  PVOID              DriverSection;
  PDRIVER_EXTENSION  DriverExtension;
  UNICODE_STRING     DriverName;
  PUNICODE_STRING    HardwareDatabase;
  PFAST_IO_DISPATCH  FastIoDispatch;
  PDRIVER_INITIALIZE DriverInit;
  PDRIVER_STARTIO    DriverStartIo;
  PDRIVER_UNLOAD     DriverUnload;
  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];
} DRIVER_OBJECT, *PDRIVER_OBJECT;

メンバー

Type

CSHORT メンバー型を定義します。

Size

CSHORT メンバーサイズを定義します。

DeviceObject

ドライバーによって作成されたデバイスオブジェクトへのポインター。ドライバーが IoCreateDevice を正常に呼び出すと、このメンバーは自動的に更新されます。ドライバーは、このメンバーと DEVICE_OBJECT の NextDevice メンバーを使用して、ドライバーが作成したすべてのデバイスオブジェクトの一覧をステップ実行できます。

Flags

ULONG メンバーフラグを定義します。

DriverStart

PVOID メンバー DriverStart を定義します。

DriverSize

ULONG メンバー DriverSize を定義します。

DriverSection

PVOID メンバー DriverSection を定義します。

DriverExtension

ドライバー拡張機能へのポインター。ドライバー拡張機能のアクセス可能なメンバーは DriverExtension-AddDevice> のみです。ドライバーの DriverEntry ルーチンは、ドライバーの AddDevice ルーチンを格納します。

DriverName

UNICODE_STRING メンバー DriverName を定義します。

HardwareDatabase

レジストリ内のハードウェア構成情報への \Registry\Machine\Hardware パスへのポインター。

FastIoDispatch

ドライバーの高速 I/O エントリポイントを定義する構造体へのポインター。このメンバーは、FSD とネットワークトランスポートドライバーでのみ使用されます。

DriverInit

I/O マネージャーによって設定される DriverEntry ルーチンのエントリポイント。

DriverStartIo

ドライバーの StartIo ルーチン (ある場合) のエントリポイント。ドライバーの初期化時に DriverEntry ルーチンによって設定されます。ドライバーに StartIo ルーチンがない場合、このメンバーは NULL です。

DriverUnload

ドライバーの Unload ルーチン (存在する場合) のエントリポイント。ドライバーの初期化時に DriverEntry ルーチンによって設定されます。ドライバーに Unload ルーチンがない場合、このメンバーは NULL です。

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

ドライバーの DispatchXxx ルーチンのエントリポイントの配列で構成されるディスパッチテーブル。配列のインデックス値は、各 IRP メジャー関数コードを表すIRP_MJ_XXX 値です。各ドライバーは、ドライバーが処理する IRP_MJ_XXX 要求のエントリポイントをこの配列に設定する必要があります。詳細については、「ディスパッチルーチンの作成」を参照してください。

ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析を支援するために、各 DispatchXxx ルーチンは、次のコード例に示すように、DRIVER_DISPATCH型を使用して宣言されます。

DRIVER_DISPATCH DispatchXxx;

その後、コールバックルーチンは次のように実装されます。

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

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

注釈

システムがドライバーを自動的に読み込むため、各カーネルモードドライバーの初期化ルーチンに DriverEntry という名前を付ける必要があります。このルーチンの名前が他の名前である場合、ドライバーライターはリンカーの初期化ルーチンの名前を定義する必要があります。それ以外の場合、システムローダーまたは I/O マネージャーは、ドライバーの転送アドレスを見つけることができません。他の標準ドライバールーチンの名前は、ドライバーライターの裁量で選択できます。

ドライバーは、ドライバーが読み込まれるときに DriverEntry ルーチンに渡されるドライバーオブジェクトの DispatchXxx エントリポイントを設定する必要があります。デバイスドライバーは、同じ種類のデバイスのドライバーが処理するために必要なIRP_MJ_XXX の 1 つ以上の DispatchXxx エントリポイントを設定する必要があります。上位レベルのドライバーは、基になるデバイスドライバーに渡す必要があるすべてのIRP_MJ_XXX に対して 1 つ以上の DispatchXxx エントリポイントを設定する必要があります。それ以外の場合、ドライバーは、ドライバーオブジェクトで DispatchXxx ルーチンを設定していないIRP_MJ_XXX の IRP は送信されません。さまざまな種類の基になるデバイスのドライバーを処理するために必要な IRP_MJ_XXX のセットの詳細については、「 IRP の主要な機能コード」を参照してください。

DriverEntry ルーチンは、ドライバーオブジェクトにドライバーの AddDevice、StartIo、Unload エントリポイント (存在する場合) も設定します。

HardwareDatabase 文字列は、ドライバーの読み込み時に、デバイスドライバーがレジストリからハードウェア構成情報を取得するために使用できます。ドライバーには、この文字列への読み取り専用アクセス権が付与されます。

DriverEntry ルーチンへの RegistryPath 入力は、\Registry\Machine\System\CurrentControlSet\Services\DriverName キーを指します。ここで、DriverName の値エントリはドライバーを識別します。入力ドライバーオブジェクトの HardwareDatabase に関しては、ドライバーにはこの文字列への読み取り専用アクセス権が付与されます。

ドライバーオブジェクト内の文書化されていないメンバーは、アクセスできないと見なす必要があります。オブジェクトメンバーの場所または文書化されていないメンバーへのアクセスに依存するドライバーは、移植性が維持されず、時間の経過と共に他のドライバーと相互運用できない可能性があります。