EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE コールバック関数 (wdfchildlist.h)

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

[KMDF にのみ適用]

ドライバーの EvtChildListIdentificationDescriptionCompare イベントコールバック関数は、1 つの子 ID の説明を別の子 ID の説明と比較します。

構文

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

パラメーター

[in] ChildList

フレームワークの子リストオブジェクトへのハンドル。

[in] FirstIdentificationDescription

1 つの子識別の説明を識別する WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 構造体へのポインター。

[in] SecondIdentificationDescription

別の子識別の説明を識別するWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER構造体へのポインター。

戻り値

EvtChildListIdentificationDescriptionCompare コールバック関数は、2 つの子 ID の説明が一致する場合に TRUE を返す必要があります。それ以外の場合、この関数は FALSE を返す必要があります。

注釈

バスドライバーが動的列挙を使用している場合は、WdfFdoInitSetDefaultChildListConfig または WdfChildListCreate を呼び出すことによって、EvtChildListIdentificationDescriptionCompare コールバック関数を登録できます。ドライバーは、WdfChildListRetrieveNextDevice を呼び出すときに、2 番目の特殊なケースの EvtChildListIdentificationDescriptionCompare コールバック関数を登録することもできます。

フレームワークは、両方の説明が同じデバイスを識別するかどうかを判断する必要がある場合に、2 つの識別の説明を比較します。

EvtChildListIdentificationDescriptionCompare コールバック関数は、2 つの識別説明の内容を比較し、一致する場合は TRUE を返す必要があります。フレームワークが RtlCompareMemory を呼び出して識別の説明を比較できない場合、ドライバーはこのコールバック関数を指定する必要があります。 (説明に追加のメモリへのポインターが含まれている場合、フレームワークは RtlCompareMemory を呼び出すことができません)。

ドライバーが EvtChildListIdentificationDescriptionCompare コールバック関数を提供しない場合、フレームワークは RtlCompareMemory を呼び出して識別の説明を比較します。

次の手順では、考えられるシナリオについて説明します。

ドライバーは WdfChildListRetrieveAddressDescription を呼び出して、フレームワークの識別説明のコピーに関連付けられているアドレスの説明を取得します。これは、子リストに格納されます。
フレームワークは子リストを走査します。子の識別の説明が、ドライバーが WdfChildListRetrieveAddressDescription を呼び出したときに指定した説明と一致するかどうかを確認するために、フレームワークは EvtChildListIdentificationDescriptionCompare コールバック関数 (存在する場合) または RtlCompareMemory を呼び出します。
2 つの識別記述が一致する場合 (および比較で TRUE が返される場合)、フレームワークはリストの走査を停止します。
フレームワークは、 WdfChildListRetrieveAddressDescription を呼び出したときにドライバーが指定したメモリにアドレスの説明をコピーします。

フレームワークでは、RtlCompareMemory を使用して識別の説明を比較できます。各説明が、WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER構造体の IdentificationDescriptionSize メンバーによって指定された事前に定義されたサイズの 1 つの構造体で構成されている場合です。ただし、場合によっては、説明に、動的に割り当てられたメモリに格納される追加情報も含まれている必要があります。この場合は、通常、メンバーが動的に割り当てられたメモリを指すように説明構造を定義し、ドライバーが EvtChildListIdentificationDescriptionCompare コールバック関数を提供する必要があります。

このコールバック関数は、2 つの識別記述が同じデバイスを表しているかどうかを判断します。コールバック関数は、その決定を行うために、すべての構造体メンバーを比較する必要がない場合があります。たとえば、次のように、ID の説明にシリアル番号とハードウェア識別子のセットが含まれているとします。

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

この場合、 EvtChildListIdentificationDescriptionCompare コールバック関数は、おそらく DeviceSerialNumber メンバーのみを比較して、2 つの説明が同じデバイスを表しているかどうかを判断する必要があります。

ドライバーが WdfChildListRetrieveNextDevice を呼び出してデバイスリストを走査する場合は、取得する次の説明を探すときにフレームワークが使用する追加の EvtChildListIdentificationDescriptionCompare コールバック関数を指定できます。フレームワークは、ドライバー提供の WDF_RETRIEVE_CHILD_FLAGS型指定フラグに一致する子デバイスを検索します。ドライバーが特別な EvtChildListIdentificationDescriptionCompare コールバック関数を提供する場合、フレームワークはコールバック関数を使用して検索を絞り込みます。ドライバーが特別な EvtChildListIdentificationDescriptionCompare コールバック関数を提供しない場合、フレームワークは RtlCompareMemory を呼び出しません。指定されたフラグに一致する各子デバイスを返すだけです。

ドライバーの EvtChildListIdentificationDescriptionCompare コールバック関数が呼び出すことができるフレームワークの子リストオブジェクトメソッドは、WdfChildListGetDevice のみです。

フレームワークは、EvtChildListIdentificationDescriptionCompare EvtChildListIdentificationDescriptionCompare コールバック関数を呼び出す前に、内部の子リスト オブジェクトロックを取得します。コールバック関数は、フレームワークメモリオブジェクトメソッドの呼び出しやオブジェクトコンテキスト空間へのアクセスなど、比較操作に関連する操作のみを実行する必要があります。他のドライバーにアクセスするメソッドを呼び出してはなりません。

動的列挙の詳細については、「バス上のデバイスの列挙」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfchildlist.h (Wdf.h を含む)
IRQL	<= DISPATCH_LEVEL