EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE回呼函式（wdfchildlist.h）

發行項
02/07/2025

[僅適用於 KMDF]

驅動程式的 EvtChildListIdentificationDescriptionDuplicate 事件回呼函式會複製子識別描述。

語法

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狀態） 等於 TRUE，則為另一個狀態值。否則，這個回呼函式必須傳回狀態值，NT_SUCCESS狀態）等於 FALSE。

言論

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

架構會複製驅動程式提供的識別描述，使其可以有描述的內部複本。

EvtChildListIdentificationDescriptionDuplicate 回調函式必須建立標識符描述的重複複本。如果架構無法呼叫 RtlCopyMemory 來複製標識符描述，驅動程式就必須提供此回呼函式。（如果描述包含其他記憶體的指標，則架構無法呼叫 RtlCopyMemory。

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

下列步驟描述一般案例：

驅動程式會判斷子裝置是否存在。
驅動程式會填入包含 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 結構的驅動程式定義結構，並可能透過動態配置額外的記憶體來儲存具有裝置特定大小的識別資訊，以建立識別描述。
驅動程式會呼叫 WdfChildListAddOrUpdateChildDescriptionAsPresent 來報告子裝置，並提供識別描述的指標。
架構會呼叫 EvtChildListIdentificationDescriptionDuplicate 回呼函式（如果存在），或 RtlCopyMemory 來複製標識符描述，讓它可以有描述的內部復本。

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

設定額外的記憶體，通常是呼叫 ExAllocatePool。
將配置的記憶體位址儲存在驅動程式定義的位址描述結構中（也就是回呼函式的 DestinationIdentificationDescription 結構）。
將回呼函式 SourceIdentificationDescription 結構的其他結構成員複製到回呼函式的 DestinationIdentificationDescription 結構。

驅動程式 EvtChildListIdentificationDescriptionDuplicate 回呼函式 WdfChildListGetDevice呼叫的唯一 framework 子清單物件方法。

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

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

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