DRIVER_OBJECT結構 (wdm.h)

發行項
02/27/2024

每個驅動程序物件都代表已載入核心模式驅動程式的影像。驅動程序物件的指標是驅動程式 DriverEntry、 AddDevice 和選擇性 Reinitialize 例程及其 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

DriverEntry 例程的進入點，由 I/O 管理員設定。

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 設定一或多個 DispatchXxx 進入點，該 IRP_MJ_XXX 需要處理相同類型裝置的任何驅動程式。較高層級的驅動程式必須針對它必須傳遞給基礎設備驅動器的所有IRP_MJ_XXX 設定一或多個 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 ，驅動程式會獲得此字串的唯讀存取權。

驅動程式物件內的未記載成員應該視為無法存取。具有對象成員位置相依性的驅動程式或未記載成員的存取權，可能無法在一段時間內保持可攜式且與其他驅動程式互通。