共用方式為

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
 ContextTypeInfo 指定 ContextAttributes 參數之WDF_OBJECT_ATTRIBUTES結構的成員無效。
資源不足狀態
 無法配置內容空間。
STATUS_OBJECT_NAME_EXISTS
 驅動程式已配置的內容空間，符合 ContextTypeInfoContextAttributes 指定之WDF_OBJECT_ATTRIBUTES結構的成員。 在此情況下，Context 參數中的指標會收到現有內容空間的指標，而且不會配置重複的內容空間。
STATUS_DELETE_PENDING
 正在刪除 Handle 參數所指定的物件。 在此情況下，架構不會配置內容空間。
 

此方法也可能 傳回其他NTSTATUS 值。

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

備註

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

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

如果您的驅動程式針對指定的物件呼叫 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
                                  );

需求

要求 價值
目標平臺 普遍
最低 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