EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY回呼函式（wdfchildlist.h）

發行項
02/07/2025

[僅適用於 KMDF]

驅動程式的 EvtChildListIdentificationDescriptionCopy 事件回呼函式會將子識別描述從一個指定的位置複製到另一個位置。

語法

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY EvtWdfChildListIdentificationDescriptionCopy;

void EvtWdfChildListIdentificationDescriptionCopy(
  [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 結構的指標。

傳回值

沒有

言論

如果總線驅動程式使用動態列舉，則可以呼叫 WdfFdoInitSetDefaultChildListConfig 或 WdfChildListCreate來註冊 EvtChildListIdentificationDescriptionCopy 回呼函式。

架構會將資訊從一個驅動程式提供的識別描述複製到另一個驅動程式，當它需要以新的資訊更新現有的描述，或當它需要將識別描述的內容傳遞給驅動程式時。

EvtChildListIdentificationDescriptionCopy 回呼函式必須將來源描述的內容複製到目的地描述。如果架構無法呼叫 RtlCopyMemory 來複製標識符描述，驅動程式就必須提供此回呼函式。（如果描述包含其他記憶體的指標，則架構無法呼叫 RtlCopyMemory。

如果您的驅動程式未提供 EvtChildListIdentificationDescriptionCopy 回呼函式，架構會呼叫 RtlCopyMemory來複製識別描述。

下列步驟描述可能的案例：

周遊子清單的驅動程式會呼叫 WdfChildListRetrieveNextDevice。驅動程式會提供 WDF_CHILD_RETRIEVE_INFO 結構，以便接收子裝置的識別描述。
架構會呼叫 EvtChildListIdentificationDescriptionCopy 回呼函式（如果存在），或 RtlCopyMemory 來複製裝置的識別描述。複製作業的來源是架構的描述內部複本。目的地是驅動程式在其WDF_CHILD_RETRIEVE_INFO結構中配置和識別的記憶體。

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

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

驅動程式 EvtChildListIdentificationDescriptionCopy 回呼函式 WdfChildListGetDevice，架構子清單物件方法。

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

如果您的驅動程式提供 EvtChildListIdentificationDescriptionCopy 回呼函式，則可能也需要 EvtChildListIdentificationDescriptionDuplicate、EvtChildListIdentificationDescriptionCompare，以及 EvtChildListIdentificationDescriptionCleanup 回呼函式。

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