WDF_OBJECT_ATTRIBUTES 结构 (wdfobject.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WDF_OBJECT_ATTRIBUTES 结构描述可与任何框架对象关联的属性。

语法

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

成员

Size

此结构的大小（以字节为单位）。

EvtCleanupCallback

指向驱动程序的 EvtCleanupCallback 回调函数或 NULL 的指针。

EvtDestroyCallback

指向驱动程序的 EvtDestroyCallback 回调函数的指针，或 NULL。

ExecutionLevel

一个WDF_EXECUTION_LEVEL类型的值，该值指定框架调用对象的事件回调函数时的最大 IRQL。有关驱动程序可以指定 ExecutionLevel 值的框架对象的列表，请参阅 WDF_EXECUTION_LEVEL。

SynchronizationScope

一个WDF_SYNCHRONIZATION_SCOPE类型的值，该值指定框架如何同步对象的事件回调函数的执行。有关驱动程序可以指定 SynchronizationScope 值的框架对象的列表，请参阅 WDF_SYNCHRONIZATION_SCOPE。

ParentObject

对象的父对象的句柄;如果对象没有驱动程序指定的父对象，则为 NULL 。

有关显示允许驱动程序指定父级的对象的表，请参阅框架对象摘要。该表还显示了每个对象的默认父级。

ContextSizeOverride

如果不是零，此值将替代 ContextTypeInfo 成员引用的 WDF_OBJECT_CONTEXT_TYPE_INFO 结构的 ContextSize 成员。此值是可选的，可以为零。如果值不为零，则必须指定一个大小（以字节为单位），该值大于为 WDF_OBJECT_CONTEXT_TYPE_INFO 结构的 ContextSize 成员指定的值。有关更多信息，请参见下面的“备注”部分。

ContextTypeInfo

指向 WDF_OBJECT_CONTEXT_TYPE_INFO 结构的指针。 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE宏设置此指针。

注解

WDF_OBJECT_ATTRIBUTES 结构用作多个创建框架对象的方法的输入参数。

若要初始化WDF_OBJECT_ATTRIBUTES结构，驱动程序必须调用 WDF_OBJECT_ATTRIBUTES_INIT。

此外，如果要为对象定义特定于对象的上下文信息，则必须使用 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 宏。

或者，可以使用 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE 宏而不是WDF_OBJECT_ATTRIBUTES_INIT宏和WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE宏。

有关使用这些宏的详细信息，请参阅框架对象上下文空间。

如果要创建长度可变的对象上下文空间，请使用 WDF_OBJECT_ATTRIBUTES 的 ContextSizeOverride 成员。例如，可以定义包含数组的上下文空间结构，如下所示：

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

当驱动程序创建使用上下文空间结构的对象时，它可以使用 ContextSizeOverride 成员来指定每个单独对象所需的上下文大小。例如，驱动程序可能会计算前面示例中数组中所需的字节数，然后使用 ContextSizeOverride 指定额外的字节，如下所示：

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

然后，驱动程序可以创建具有自定义上下文大小的对象。

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

有关框架对象层次结构的清理规则的详细信息，请参阅框架对象生命周期。