WDF_QUERY_INTERFACE_CONFIG 構造体 (wdfqueryinterface.h)

[アーティクル]
08/08/2023

[KMDF にのみ適用]

WDF_QUERY_INTERFACE_CONFIG構造体は、ドライバー定義インターフェイスを記述します。

構文

typedef struct _WDF_QUERY_INTERFACE_CONFIG {
  ULONG                                          Size;
  PINTERFACE                                     Interface;
  const GUID                                     *InterfaceType;
  BOOLEAN                                        SendQueryToParentStack;
  PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
  BOOLEAN                                        ImportInterface;
} WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;

メンバー

Size

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

Interface

ドライバー定義インターフェイスを記述する INTERFACE 構造体へのポインター。

InterfaceType

インターフェイスを識別する GUID へのポインター。

注意

既存のインターフェイスの新しいバージョンを導入する場合は、INTERFACE 構造体の [サイズ] フィールドまたは [バージョン] フィールドを変更する代わりに、新しい GUID を作成します。詳細については、「 Driver-Defined インターフェイスの使用」を参照してください。

SendQueryToParentStack

TRUE の場合、ドライバーが WdfDeviceAddQueryInterface を呼び出すときに物理デバイスオブジェクト (PDO) を表すデバイスオブジェクトを指定した場合、フレームワークはインターフェイスの要求を親デバイスのドライバースタックの先頭に送信します。このメンバーが FALSE の場合、またはデバイスオブジェクトが PDO を表していない場合、フレームワークは親デバイスのスタックに要求を送信しません。詳細については、「解説」を参照してください。

EvtDeviceProcessQueryInterfaceRequest

別のドライバーがインターフェイスを要求したときに呼び出される、ドライバーの EvtDeviceProcessQueryInterfaceRequest イベントコールバック関数へのポインター。

ImportInterface

TRUE の場合、インターフェイスは、ドライバーとインターフェイスを要求するドライバー間の双方向通信をサポートします。

このメンバーが FALSE の場合、インターフェイスは、ドライバーからインターフェイスを要求するドライバーへの一方向の通信をサポートします。

注釈

WDF_QUERY_INTERFACE_CONFIG構造体は、WdfDeviceAddQueryInterface メソッドへの入力として使用されます。

ドライバーがエクスポートするドライバー定義インターフェイスごとに、インターフェイスを表すWDF_QUERY_INTERFACE_CONFIG構造体を割り当てる必要があります。他のドライバーは、WdfFdoQueryForInterface を呼び出すことによって、インターフェイスへのアクセスを要求できます。

要求しているドライバーとドライバー間の双方向通信をインターフェイスでサポートする場合は、 ImportInterface メンバーを TRUE に設定 します。 ImportInterface が TRUE の場合、要求側のドライバーによって提供される構造体には、ドライバーが読み取ることができるデータを含めることができます。この場合、次のようになります。

EvtDeviceProcessQueryInterfaceRequest コールバック関数が必要であり、要求側ドライバーが提供するインターフェイス構造を初期化する必要があります。
EvtDeviceProcessQueryInterfaceRequest コールバック関数は要求側ドライバーにインターフェイスを提供するため、WDF_QUERY_INTERFACE_CONFIG の Interface メンバーは NULL にすることができます。 NULL 以外のポインターを指定した場合、フレームワークは、要求するドライバーが提供するサイズとバージョンの値が、登録済みの INTERFACE 構造体の値以上であることを確認します。これらの値のいずれかが小さい場合、フレームワークは要求を拒否します。 Interface に値を指定しない場合は、EvtDeviceProcessQueryInterfaceRequest コールバック関数でこれらの値を確認する必要があります。

インターフェイスでドライバーから要求元ドライバーへの一方向の通信のみをサポートする場合は、 ImportInterface を FALSE に設定します。要求するドライバーが提供するインターフェイス構造は、ドライバーが提供するデータのみを受け取ることができます。この場合、次のようになります。

EvtDeviceProcessQueryInterfaceRequest コールバック関数は省略可能です。
Interface メンバーを NULL にすることはできません。フレームワークは、要求元のドライバーが提供する GUID、サイズ、バージョンの値が指定した GUID と一致することを確認し、値が一致しない場合、フレームワークは要求を拒否します。値が有効な場合、フレームワークは、Interface に指定した値を使用して、要求側ドライバーが提供するインターフェイス構造を初期化 します。

また、SendQueryToParentStack メンバーの値が TRUE の場合は、Interface メンバーを NULL にすることができます。

Interface メンバーが NULL 以外の場合、フレームワークは値を内部ストレージ領域にコピーします。そのため、ドライバーは、ローカルの一時的な記憶域スペースに INTERFACE 構造体を割り当てることができます。

ドライバーが WdfDeviceAddQueryInterface を呼び出すと、機能デバイスオブジェクト (FDO) または物理デバイスオブジェクト (PDO) を表すフレームワークデバイスオブジェクトにインターフェイスを関連付けることができます。ドライバーがインターフェイスを PDO に関連付ける場合は、WDF_QUERY_INTERFACE_CONFIG構造体の SendQueryToParentStack メンバーを TRUE に設定できます。フレームワークは、インターフェイスの要求をインターセプトすると、 SendQueryToParentStack メンバーを確認し、 TRUE に設定されている場合、フレームワークは PDO の親のドライバースタックの上部に要求を送信します。その結果、要求は 2 つのドライバースタックを移動します。1 つ目は、インターフェイスを要求しているドライバーを含むスタック、2 つ目はインターフェイスのデバイスの親のスタックです。

フレームワークには、INTERFACE 構造体の InterfaceReference メンバーと InterfaceDereference メンバーのアドレスを指定することで、インターフェイスで使用できる 2 つの参照/逆参照メソッドが用意されています。これらのメソッドの詳細については、「 WdfDeviceInterfaceReferenceNoOp 」および「 WdfDeviceInterfaceDereferenceNoOp」を参照してください。

ドライバーは、WDF_QUERY_INTERFACE_CONFIG_INITを呼び出して、この構造体を初期化する必要があります。

ドライバー定義インターフェイスの詳細については、「 Driver-Defined インターフェイスの使用」を参照してください。