共用方式為

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。 否則，此方法可能會傳回下列其中一個值：

傳回碼 Description
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值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

一般而言，驅動程式會藉由在呼叫架構物件的建立方法時指定 WDF_OBJECT_ATTRIBUTES 結構來建立對象內容空間，例如 WdfDeviceCreate。

如果您想要讓驅動程式將多個內容空間類型配置給其中一些對象，驅動程式可以在呼叫物件建立方法之後呼叫 WdfObjectAllocateContext 一或多次。 每個對 WdfObjectAllocateContext 的呼叫都必須指定不同的內容類型。 (WDF_OBJECT_ATTRIBUTES 結構的 ContextTypeInfo 成員會識別內容類型。)

如果您的驅動程式針對指定的物件多次呼叫 WdfObjectAllocateContext ，您可以為每個內容提供個別的 EvtCleanupCallback 和 EvtDestroyCallback 回 呼函式。

呼叫 WdfObjectAllocateContext 時，請勿在 WDF_OBJECT_ATTRIBUTES 結構中指定 ParentObject。

當架構配置對象的內容空間時，也會以零初始化內容空間。

如需對象內容空間的詳細資訊，請參閱 Framework 對象內容空間。

如需架構物件階層清除規則的詳細資訊，請參閱 Framework 物件生命週期。

範例

下列程式代碼範例會建立要求對象的內容空間。 內容空間是以範例的 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
                                  );

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfobject.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DriverCreate (kmdf)

另請參閱

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate