框架对象上下文空间

对象上下文空间 是驱动程序可以分配和分配给对象的额外、不可分页的内存空间。 每个基于框架的驱动程序都可以为驱动程序接收或创建的每个框架对象创建一个或多个特定于对象的上下文空间。

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

例如,USB 设备的驱动程序可能会为框架设备对象创建上下文空间。 在上下文空间中,驱动程序可能会存储设备特定的信息,例如设备的 USB_DEVICE_DESCRIPTORUSB_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 定义全局数据结构并创建可调用驱动程序的例程,因此驱动程序必须在声明全局数据的驱动程序区域(通常为头文件)中完成这些步骤。 这些步骤不能从驱动程序的例程中完成。

驱动程序必须在创建对象的驱动程序例程(如调用 WdfDeviceCreateEvtDriverDeviceAdd 回调函数)中完成步骤 3、4 和 5。

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

创建对象后,驱动程序可以使用以下方法之一获取指向对象的上下文空间的指针:

如果驱动程序具有上下文空间指针,则可以通过调用 WdfObjectContextGetObject 找到上下文空间所属的对象。