windows驱动开发-WDF对象

WDF封装了大量的WDF对象，不过，和应用层不一样，不用去尝试从WDF框架对象类上派生和改写原有的WDF类，本意WDF就是希望我们使用这些对象和类，而不是创造新的奇怪的类。

每个WDF对象都代表着对一项驱动需要使用的子功能的封装；WDF对象本身存在是和WDF框架导出的函数接口对应的;另外，每个版本的WDF可能会有细微的差别。

WDF对象

WDF提供给驱动程序的接口是基于对象的, 框架会定义多个对象和接口。这些对象导出方法 (函数) 和属性 (驱动程序可以访问的数据) 。框架对象还会启动事件，驱动程序可以通过提供事件回调函数来支持这些事件。

基于框架的驱动程序永远不会直接访问框架对象，这是因为不同版本之间对象的内存布局有细微的差别。驱动程序按句柄引用对象，驱动程序将其作为输入传递给对象的方法。下面列出了所有的WDF对象:

所有框架对象具有以下特征：

引用计数：框架维护对每个对象的引用数。当框架创建对象时，它将对象的引用计数设置为 1。当框架使用完对象后，它会递减引用计数。在引用计数减为零之前，框架无法删除对象，因此驱动程序可以通过递增对象的引用计数来阻止删除该对象。

上下文空间：基于框架的驱动程序可以为驱动程序接收或创建的每个框架对象创建特定于对象的上下文空间。驱动程序应将所有特定于对象的数据存储在对象的上下文空间中。

删除回调函数：驱动程序可以注册框架在删除对象时调用的回调函数。回调函数可以删除驱动程序分配的资源，例如特定于对象的内存分配。

父对象：所有框架对象都可以具有父对象。 WDF框架为大多数对象指定默认父对象。当驱动程序创建对象时，它可以指定替代该对象的默认父对象的父对象。若要指定对象的父对象，驱动程序设置对象的WDF_OBJECT_ATTRIBUTES结构的 ParentObject 成员。对于少数对象类型，驱动程序无法替代默认的父对象，框架或驱动程序删除父对象时，框架也会删除父对象的子对象。

生命周期

WDF框架对象的“生命周期”跨越从创建对象到删除对象的时间，对象的引用计数控制何时将其删除。下面是一些生命周期节点中的特点:

创建框架对象：大多数框架对象都是通过驱动程序调用对象的创建方法创建的。例如，每个框架驱动程序必须调用 WdfDriverCreate 来创建框架驱动程序对象。

其他框架对象由框架创建。例如，当用户应用程序打开设备进行读取或写入操作时，框架会创建一个框架文件对象，并将其传递给驱动程序的 EvtDeviceFileCreate 回调函数。

框架或驱动程序可以创建一些框架对象。例如，当 I/O 管理器将 I/O 请求传递到驱动程序时，框架会创建一个框架请求对象并将其传递给驱动程序，通常通过调用驱动程序的请求处理程序之一。驱动程序还可以创建框架请求对象并将其传递给其他驱动程序。

使用引用计数: 框架为每个对象维护引用计数。创建对象时，框架将其引用计数设置为 1。如果引用计数变为零，框架将删除对象。

驱动程序可以通过调用 WdfObjectReference 来递增引用计数或调用 WdfObjectDereference 来递减引用计数来修改对象的引用计数。

在大多数情况下，驱动程序不必递增或递减对象的引用计数。框架在将对象的句柄传递给驱动程序之前递增计数，并在驱动程序不再需要该对象时递减计数。

驱动程序调用 WdfObjectReference 以确保在驱动程序使用完对象之前，不会由框架或驱动程序线程删除对象。

删除框架对象: 对象被删除是因为驱动程序调用 WdfObjectDelete 或框架调用内部删除例程，但仅当对象的引用计数为零时才被删除。驱动程序或框架尝试删除对象后，对象的句柄将保持有效，直到引用计数变为零。驱动程序无法通过调用 WdfObjectDereference 将对象的引用计数减少到零来删除对象-驱动程序还必须调用 WdfObjectDelete。

如果框架对象是父对象的子对象，并且正在删除父对象，则框架会尝试先删除子对象，然后再删除父对象。对象删除从离父级最远的对象开始，并针对根目录执行对象层次结构。

驱动程序可以注册驱动程序或框架删除对象时框架调用的以下两个回调函数：

EvtCleanupCallback 回调函数，框架调用该函数，以便驱动程序可以调用 WdfObjectDereference（如果它以前为要删除的对象调用 WdfObjectReference）。

EvtDestroyCallback 回调函数，框架在对象的引用计数减至零后调用该回调函数。

其中一个回调函数必须解除分配驱动程序在创建对象时分配的任何特定于对象的资源。

框架始终处理某些框架对象的删除，驱动程序不得尝试删除这些对象，例如驱动对象。

框架对象的上下文

在WDM时代，驱动程序的设备对象有一个设备扩展，这个设备扩展绑定了设备对象，用于存储设备相关的信息，这使得每个设备对象都有自己的设备扩展部分，此时驱动程序导出的例程可以利用设备扩展来避免重入，这样几乎不需要为区分多个设备对象浪费额外的代码，例程天然就是可重入的。

这一良好的设计也延续到了WDF中，几乎所有WDF对象都可以分配上下文，对象上下文空间是驱动程序可以分配和分配给对象的额外、不可分页的内存空间。每个基于框架的驱动程序都可以为驱动程序接收或创建的每个框架对象创建一个或多个特定于对象的上下文空间。

基于框架的驱动程序应在数据所属对象的上下文空间中按值或指针存储所有特定于对象的数据。

例如，USB 设备的驱动程序可能会为其框架设备对象创建上下文空间。在上下文空间中，驱动程序可能会存储设备特定的信息，例如设备的 USB_DEVICE_DESCRIPTOR 和 USB_CONFIGURATION_DESCRIPTOR 结构，以及表示设备接口管道的集合对象的句柄。

框架不会将框架对象从一个驱动程序传递到另一个驱动程序，因此不能使用对象的上下文空间在两个驱动程序之间传递数据。

若要定义对象的上下文空间，必须创建一个或多个结构。每个结构表示单独的上下文空间。驱动程序将使用每个结构成员来存储一段特定于对象的信息。此外，驱动程序必须要求框架为每个结构生成访问器方法。此访问器方法接受对象句柄作为输入，并返回对象的上下文空间的地址。

每当驱动程序调用对象创建方法（如 WdfDeviceCreate）时，该方法会选择性地分配上下文空间。所有对象创建方法都接受可选的 WDF_OBJECT_ATTRIBUTES 结构作为输入。此结构描述希望框架为对象分配的上下文空间。

若要在驱动程序调用对象的创建方法后向对象添加额外的上下文空间，驱动程序可以调用 WdfObjectAllocateContext 方法，该方法与对象创建方法一样，接受 WDF_OBJECT_ATTRIBUTES 结构作为输入。

当框架为对象分配上下文空间时，它还对上下文空间进行零初始化。

当框架或驱动程序删除框架对象时，框架将删除该对象的所有上下文空间。

如果驱动程序使用上下文空间来存储指向驱动程序在创建对象时分配的缓冲区的指针，则驱动程序应提供一个 EvtCleanupCallback 函数，该函数在删除对象时解除分配缓冲区。

若要为驱动程序创建的对象定义对象的上下文空间结构和访问器方法，驱动程序必须使用以下步骤：

1. 定义描述要存储的数据的结构。例如，如果要为驱动程序的设备对象创建上下文数据，驱动程序可能会定义一个名为 MY_DEVICE_CONTEXT 的结构。

2. 使用 WDF_DECLARE_CONTEXT_TYPE 宏或 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 宏。这两个宏都执行以下操作：

创建并初始化 WDF_OBJECT_CONTEXT_TYPE_INFO 结构。
定义一个访问器方法，驱动程序稍后将使用该方法访问对象的上下文空间。访问器方法的返回值是指向对象的上下文空间的指针。

WDF_DECLARE_CONTEXT_TYPE宏根据结构的名称创建访问器方法的名称。例如，如果上下文结构的名称MY_DEVICE_CONTEXT，则宏将创建一个名为 WdfObjectGet_MY_DEVICE_CONTEXT 的访问器方法。

使用 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 宏可以指定访问器方法的名称。例如，可以将 GetMyDeviceContext 指定为设备对象的上下文访问器方法的名称。

3. 调用 WDF_OBJECT_ATTRIBUTES_INIT 以初始化对象的 WDF_OBJECT_ATTRIBUTES 结构。

4. 使用 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 宏将 WDF_OBJECT_ATTRIBUTES 结构的 ContextTypeInfo 成员设置为 WDF_OBJECT_CONTEXT_TYPE_INFO 结构的地址。

5. 调用对象创建方法，例如 WdfDeviceCreate。

驱动程序创建对象后，驱动程序可以随时调用 WdfObjectAllocateContext ，以向对象添加额外的上下文空间。

由于步骤 1 和步骤 2 定义全局数据结构并创建驱动程序可调用的例程，因此驱动程序必须在声明全局数据的驱动程序区域中完成这些步骤，通常为头文件。这些步骤不得从驱动程序的例程中完成。

驱动程序必须从创建对象的驱动程序例程中完成步骤 3、4 和 5。

框架可以代表驱动程序创建两种类型的对象（框架请求对象和框架文件对象）。驱动程序可以通过分别调用 WdfDeviceInitSetRequestAttributes 和 WdfDeviceInitSetFileObjectConfig 来注册这些对象的上下文空间。驱动程序还可以调用 WdfObjectAllocateContext 来为这些对象分配上下文空间。

创建对象后，驱动程序可以通过使用以下任一技术获取指向对象的上下文空间的指针：