wdm.h) (DRIVER_OBJECT 结构

项目
03/08/2023

每个驱动程序对象都表示加载的内核模式驱动程序的映像。指向驱动程序对象的指针是驱动程序的 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 设置一个或多个 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 ，向驱动程序授予对此字符串的只读访问权限。

驱动程序对象中的未记录成员应被视为不可访问。随着时间的推移，依赖于对象成员位置或访问未记录成员的驱动程序可能无法保持可移植和与其他驱动程序的互操作。