EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY回呼函式 (wdfchildlist.h)

發行項
02/29/2024

[僅適用於 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結構中配置和識別的記憶體。

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

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

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

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

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

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