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

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

[KMDF にのみ適用]

ドライバーの EvtChildListAddressDescriptionCopy イベントコールバック関数は、指定した場所から別の場所に子アドレスの説明をコピーします。

構文

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

パラメーター

[in] ChildList

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

[in] SourceAddressDescription

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

[out] DestinationAddressDescription

子アドレスの説明の宛先の場所を識別するWDF_CHILD_ADDRESS_DESCRIPTION_HEADER構造体へのポインター。

戻り値

なし

解説

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

フレームワークは、既存の説明を新しい情報で更新する必要がある場合、またはアドレスの説明の内容をドライバーに渡す必要がある場合に、ドライバーから別のアドレスの説明に情報をコピーします。

EvtChildListAddressDescriptionCopy コールバック関数は、ソースの説明の内容をコピー先の説明にコピーする必要があります。ドライバーは、子デバイスでアドレスの説明が必要な場合、およびフレームワークが RtlCopyMemory を呼び出してアドレスの説明をコピーできない場合は、このコールバック関数を指定する必要があります。 (説明に追加のメモリへのポインターが含まれている場合、フレームワークは RtlCopyMemory を呼び出すことができません)。

ドライバーがアドレスの説明を提供し、 EvtChildListAddressDescriptionCopy コールバック関数を提供しない場合、フレームワークは RtlCopyMemory を呼び出してアドレスの説明をコピーします。

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

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

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

コールバック関数の SourceAddressDescription 構造体と DestinationAddressDescription 構造体で、動的に割り当てられたメモリへのポインターを見つけます。
ポインターを使用して、ソースから宛先に動的に割り当てられたメモリをコピーします。
コールバック関数の SourceAddressDescription 構造体からコールバック関数の DestinationAddressDescription 構造体に他の構造体メンバーをコピーします。

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

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

ドライバーが EvtChildListAddressDescriptionCopy コールバック関数を提供する場合は、 EvtChildListAddressDescriptionDuplicate および EvtChildListAddressDescriptionCleanup コールバック関数も必要になる場合があります。

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

要件

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