WDF_OBJECT_ATTRIBUTES構造体 (wdfobject.h)

2025-03-22

[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
                          );

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