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

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

[KMDF にのみ適用]

ドライバーの EvtChildListIdentificationDescriptionDuplicate イベントコールバック関数は、子 ID の説明を複製します。

構文

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

パラメーター

[in] ChildList

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

[in] SourceIdentificationDescription

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

[out] DestinationIdentificationDescription

重複する子識別の説明の宛先の場所を識別するWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER構造体へのポインター。

戻り値

EvtChildListIdentificationDescriptionDuplicate コールバック関数は、STATUS_SUCCESS、または操作が成功した場合にNT_SUCCESS(status) が TRUE に等しい別の状態値を返す必要があります。それ以外の場合、このコールバック関数は、NT_SUCCESS(status) が FALSE である状態値を返す必要があります。

注釈

バスドライバーが動的列挙を使用している場合は、WdfFdoInitSetDefaultChildListConfig または WdfChildListCreate を呼び出すことによって、EvtChildListIdentificationDescriptionDuplicate コールバック関数を登録できます。

フレームワークは、ドライバーが提供する識別の説明を複製して、説明の内部コピーを作成できるようにします。

EvtChildListIdentificationDescriptionDuplicate コールバック関数は、識別記述の複製コピーを作成する必要があります。フレームワークが RtlCopyMemory を呼び出して識別の説明を複製できない場合、ドライバーはこのコールバック関数を指定する必要があります。 (説明に追加のメモリへのポインターが含まれている場合、フレームワークは RtlCopyMemory を呼び出すことができません)。

ドライバーが EvtChildListIdentificationDescriptionDuplicate コールバック関数を提供しない場合、フレームワークは RtlCopyMemory を呼び出すことによって識別の説明を複製します。

次の手順では、一般的なシナリオについて説明します。

ドライバーは、子デバイスが存在することを判断します。
ドライバーは、 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 構造体を含むドライバー定義構造体を入力し、場合によってはデバイス固有のサイズの識別情報を格納するために追加メモリを動的に割り当てることによって、識別の説明を作成します。
ドライバーは WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出して子デバイスを報告し、識別の説明へのポインターを指定します。
フレームワークは 、EvtChildListIdentificationDescriptionDuplicate コールバック関数 (存在する場合) または RtlCopyMemory を呼び出して、識別の説明を複製して、説明の内部コピーを作成できるようにします。

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

通常は ExAllocatePool を呼び出して、追加のメモリを割り当てます。
割り当てられたメモリのアドレスをドライバー定義のアドレス記述構造体 (つまり、コールバック関数の DestinationIdentificationDescription 構造体) に格納します。
コールバック関数の SourceIdentificationDescription 構造体からコールバック関数の DestinationIdentificationDescription 構造体に他の構造体メンバーをコピーします。

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

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

ドライバーが EvtChildListIdentificationDescriptionDuplicate コールバック関数を提供している場合は、 EvtChildListIdentificationDescriptionCopy、 EvtChildListIdentificationDescriptionCompare、 EvtChildListIdentificationDescriptionCleanup コールバック関数も必要になる場合があります。

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

要件

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