EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY回呼函式 (wdfchildlist.h)

發行項
02/29/2024

[僅適用於 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 來複製位址描述，則驅動程式必須提供此回呼函式。 (如果描述包含其他 memory 的指標，架構就無法呼叫 RtlCopyMemory 。)

如果您的驅動程式提供位址描述，但未提供 EvtChildListAddressDescriptionCopy 回呼函式，架構會呼叫 RtlCopyMemory 來複製位址描述。

下列步驟描述一般案例：

驅動程式會判斷子裝置存在。
驅動程式會填入包含 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 結構的驅動程式定義結構，並動態配置額外的記憶體來儲存具有裝置特定大小的地址資訊，以建立位址描述。
驅動程式會呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 來報告子裝置，並提供位址描述的指標。
架構會判斷驅動程式先前已回報裝置，因此架構可以使用新的資訊來更新裝置的舊位址描述。
架構會呼叫 EvtChildListAddressDescriptionCopy 回呼函式 (如果存在) 或 RtlCopyMemory ，即可將新的位址描述資訊複製到現有的位址描述中。

如果描述是由由 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 結構之 AddressDescriptionSize 成員所指定的單一結構所指定，架構可以使用 RtlCopyMemory 來複製位址描述。不過，有時候描述也必須包含儲存在動態配置記憶體中的其他資訊。在此情況下，您通常會定義描述結構，讓成員指向動態配置的記憶體，而您的驅動程序必須提供 EvtChildListAddressDescriptionCopy 回呼函式。回呼函式必須執行下列動作：

在回呼函式的 SourceAddressDescription 和 DestinationAddressDescription 結構中，尋找動態配置的記憶體指標。
使用指標，將動態配置的記憶體從來源複製到目的地。
將其他結構成員從回呼函式的 SourceAddressDescription 結構複製到回呼函式的 DestinationAddressDescription 結構。

驅動程式的 EvtChildListAddressDescriptionCopy 回呼函式可以呼叫的唯一架構子清單物件方法是 WdfChildListGetDevice。

架構會先取得內部子清單對象鎖定，再呼叫 EvtChildListAddressDescriptionCopy 回呼函式。回呼函式只能執行與所描述複製作業相關的作業，例如呼叫架構記憶體物件方法和存取物件內容空間。它不得呼叫存取其他驅動程式的方法。

如果您的驅動程式提供 EvtChildListAddressDescriptionCopy 回呼函式，可能也需要 EvtChildListAddressDescriptionDuplicate 和 EvtChildListAddressDescriptionCleanup 回呼函式。

如需動態列舉的詳細資訊，請參閱列舉總線上的裝置。