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 値も返す場合があります。

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

注釈

通常、ドライバーは、フレームワーク オブジェクトの作成メソッド (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
                                  );

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header 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