WdfObjectAllocateContext 函数 (wdfobject.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfObjectAllocateContext 方法为指定的框架对象分配上下文空间。

语法

NTSTATUS WdfObjectAllocateContext(
  [in]  WDFOBJECT              Handle,
  [in]  PWDF_OBJECT_ATTRIBUTES ContextAttributes,
  [out] PVOID                  *Context
);

参数

[in] Handle

框架对象的句柄。

[in] ContextAttributes

指向调用方提供的 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构描述上下文空间。

[out] Context

指向位置的指针，该位置接收指向已分配上下文空间的指针。

返回值

如果操作成功，WdfObjectAllocateContext 将返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：

返回代码 说明
STATUS_INVALID_PARAMETER
 检测到参数无效。
STATUS_OBJECT_NAME_INVALID
 指定的 ContextAttributes 参数无效的WDF_OBJECT_ATTRIBUTES结构的 ContextTypeInfo 成员。
STATUS_INSUFFICIENT_RESOURCES
 无法分配上下文空间。
STATUS_OBJECT_NAME_EXISTS
 驱动程序已分配与 ContextAttributes 指定的WDF_OBJECT_ATTRIBUTES结构的 ContextTypeInfo 成员匹配的上下文空间。 在这种情况下， Context 参数中的指针接收指向现有上下文空间的指针，并且不会分配重复的上下文空间。
STATUS_DELETE_PENDING
 正在删除 Handle 参数指定的 对象。 在这种情况下，框架不会分配上下文空间。
 

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

通常，驱动程序在调用框架对象的创建方法（如 WdfDeviceCreate）时，通过指定WDF_OBJECT_ATTRIBUTES结构来创建对象上下文空间。

如果希望驱动程序为其某些对象分配多种类型的上下文空间，驱动程序可以在调用对象的创建方法后调用 WdfObjectAllocateContext 一次或多次。 每次调用 WdfObjectAllocateContext 都必须指定不同的上下文类型。 (WDF_OBJECT_ATTRIBUTES 结构的 ContextTypeInfo 成员标识上下文类型。)

如果驱动程序为给定对象多次调用 WdfObjectAllocateContext ，则可以为每个上下文提供单独的 EvtCleanupCallback 和 EvtDestroyCallback 回调函数。

调用 WdfObjectAllocateContext 时，请勿在 WDF_OBJECT_ATTRIBUTES 结构中指定 ParentObject。

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

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

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

示例

下面的代码示例为请求对象创建上下文空间。 上下文空间基于示例的REQUEST_CONTEXT结构。

typedef struct _REQUEST_CONTEXT {
  WDFMEMORY InputMemoryBuffer;
  WDFMEMORY OutputMemoryBuffer;
} REQUEST_CONTEXT, *PREQUEST_CONTEXT;

PREQUEST_CONTEXT  reqContext = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &attributes,
                                        REQUEST_CONTEXT
                                        );
status = WdfObjectAllocateContext(
                                  Request,
                                  &attributes,
                                  &reqContext
                                  );

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfobject.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf)

另请参阅

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate