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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

このメソッドは、他の NTSTATUS 値も返す場合があります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

通常、ドライバーは、フレームワーク オブジェクトの作成メソッド (WdfDeviceCreate など) を呼び出すときに、WDF_OBJECT_ATTRIBUTES構造体を指定してオブジェクト コンテキスト空間を作成します。

ドライバーで複数の種類のコンテキスト領域をそのオブジェクトの一部に割り当てる場合、ドライバーは、オブジェクトの作成メソッドを呼び出した後、 WdfObjectAllocateContext を 1 回以上呼び出すことができます。 WdfObjectAllocateContext を呼び出すたびに、異なるコンテキストの種類を指定する必要があります。 (WDF_OBJECT_ATTRIBUTES構造体の ContextTypeInfo メンバーは、コンテキストの種類を識別します)。

ドライバーが特定のオブジェクトに対して WdfObjectAllocateContext を 複数回呼び出す場合は、コンテキストごとに 個別の EvtCleanupCallback コールバック関数と EvtDestroyCallback コールバック関数を指定できます。

WdfObjectAllocateContext を呼び出すときは、WDF_OBJECT_ATTRIBUTES構造体で ParentObject を指定しないでください。

フレームワークがオブジェクトにコンテキスト領域を割り当てると、コンテキスト空間も 0 初期化されます。

オブジェクト コンテキスト空間の詳細については、「 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
                                  );

要件

こちらもご覧ください

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate