WDF_OBJECT_ATTRIBUTES 構造体 (wdfobject.h)

[アーティクル]
02/27/2024

[KMDF と UMDF に適用]

WDF_OBJECT_ATTRIBUTES構造体は、任意のフレームワークオブジェクトに関連付けることができる属性を記述します。

構文

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

メンバー

Size

この構造体のサイズ (バイト単位)。

EvtCleanupCallback

ドライバーの EvtCleanupCallback コールバック関数 ( NULL) へのポインター。

EvtDestroyCallback

ドライバーの EvtDestroyCallback コールバック関数 ( NULL) へのポインター。

ExecutionLevel

フレームワークがオブジェクトのイベントコールバック関数を呼び出す最大 IRQL を指定する、 WDF_EXECUTION_LEVEL型指定された値。ドライバーで ExecutionLevel 値を指定できるフレームワークオブジェクトの一覧については、「 WDF_EXECUTION_LEVEL」を参照してください。

SynchronizationScope

フレームワークがオブジェクトのイベントコールバック関数の実行を同期する方法を指定する、 WDF_SYNCHRONIZATION_SCOPE型指定された値。ドライバーで SynchronizationScope 値を指定できるフレームワークオブジェクトの一覧については、「 WDF_SYNCHRONIZATION_SCOPE」を参照してください。

ParentObject

オブジェクトの親オブジェクトへのハンドル。オブジェクトにドライバー指定の親がない場合は NULL 。

ドライバー指定の親を許可するオブジェクトを示すテーブルについては、「Framework オブジェクトの概要」を参照してください。表には、各オブジェクトの既定の親も示されています。

ContextSizeOverride

0 でない場合、この値は ContextTypeInfo メンバーが参照するWDF_OBJECT_CONTEXT_TYPE_INFO構造体の ContextSize メンバーをオーバーライドします。この値は省略可能であり、0 にすることができます。値が 0 でない場合は、WDF_OBJECT_CONTEXT_TYPE_INFO構造体の ContextSize メンバーに指定された値より大きいサイズ (バイト単位) を指定する必要があります。詳細については、「解説」を参照してください。

ContextTypeInfo

WDF_OBJECT_CONTEXT_TYPE_INFO構造体へのポインター。 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE マクロは、このポインターを設定します。

注釈

WDF_OBJECT_ATTRIBUTES構造体は、フレームワークオブジェクトを作成するいくつかのメソッドへの入力引数として使用されます。

WDF_OBJECT_ATTRIBUTES構造体を初期化するには、ドライバーが WDF_OBJECT_ATTRIBUTES_INIT を呼び出す必要があります。

さらに、オブジェクトに対してオブジェクト固有のコンテキスト情報を定義する場合は、 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE マクロを使用する必要があります。

または、WDF_OBJECT_ATTRIBUTES_INITマクロと WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE マクロではなく、WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE マクロを使用することもできます。

これらのマクロの使用方法の詳細については、「 Framework オブジェクトコンテキスト空間」を参照してください。

可変長のオブジェクトコンテキスト空間を作成する場合は、WDF_OBJECT_ATTRIBUTES の ContextSizeOverride メンバーを使用します。たとえば、次のように、配列を含むコンテキスト空間構造を定義できます。

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

ドライバーは、コンテキスト空間構造を使用するオブジェクトを作成するときに、 ContextSizeOverride メンバーを使用して、個々のオブジェクトに必要なコンテキストサイズを指定できます。たとえば、ドライバーは、前の例の配列に必要なバイト数を計算し、 次のように ContextSizeOverride を使用して余分なバイトを指定します。

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

その後、ドライバーは、カスタマイズされたコンテキストサイズを持つオブジェクトを作成できます。

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

フレームワークオブジェクト階層のクリーンアップ規則の詳細については、「フレームワークオブジェクトのライフサイクル」を参照してください。