EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE回呼函式（wdfchildlist.h）

發行項
02/07/2025

[僅適用於 KMDF]

驅動程式的 EvtChildListIdentificationDescriptionCompare 事件回呼函式會比較一個子識別描述與另一個子識別描述。

語法

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

參數

[in] ChildList

架構子清單物件的句柄。

[in] FirstIdentificationDescription

識別一個子識別描述之 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 結構的指標。

[in] SecondIdentificationDescription

識別另一個子識別描述之WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER結構的指標。

傳回值

如果兩個子識別描述相符，則 EvtChildListIdentificationDescriptionCompare 回呼函式必須傳回 true true。否則，此函式必須傳回 FALSE。

言論

如果總線驅動程式使用動態列舉，則可以呼叫 WdfFdoInitSetDefaultChildListConfig 或 WdfChildListCreate來註冊 EvtChildListIdentificationDescriptionCompare 回呼函式。驅動程式也可以在呼叫 WdfChildListRetrieveNextDevice時，註冊第二個特殊案例 EvtChildListIdentificationDescriptionCompare 回呼函式。

架構會在必須判斷這兩個描述是否識別相同的裝置時，比較兩個識別描述。

EvtChildListIdentificationDescriptionCompare 回呼函式必須比較兩個識別描述的內容，並在符合時傳回 TRUE。如果架構無法呼叫 RtlCompareMemory 來比較識別描述，驅動程式就必須提供此回呼函式。（如果描述包含其他記憶體的指標，則架構無法呼叫 RtlCompareMemory。

如果您的驅動程式未提供 EvtChildListIdentificationDescriptionCompare 回呼函式，則架構會呼叫 RtlCompareMemory來比較識別描述。

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

驅動程式會呼叫 WdfChildListRetrieveAddressDescription，以取得與架構標識符描述複本相關聯的位址描述，該復本會儲存在子清單中。
架構會周遊子清單。若要判斷子系的識別描述是否符合驅動程式在 WdfChildListRetrieveAddressDescription時指定的標識符描述，架構會呼叫 EvtChildListIdentificationDescriptionCompare 回呼函式（如果有的話），或 RtlCompareMemory。
如果兩個識別描述相符（而比較傳回 TRUE），架構就會停止周遊清單。
架構會將位址描述複製到驅動程式呼叫 WdfChildListRetrieveAddressDescription時所提供的記憶體。

架構可以使用 RtlCompareMemory 來比較識別描述，如果每個描述是由 IdentificationDescriptionSize 所指定之預先決定大小的單一結構所組成， 則 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 結構的成員。不過，有時候描述也必須包含儲存在動態配置記憶體中的其他資訊。在此情況下，您通常會定義描述結構，讓成員指向動態配置的記憶體，而您的驅動程序必須提供 EvtChildListIdentificationDescriptionCompare 回呼函式。

此回呼函式會判斷兩個識別描述是否代表相同的裝置。回呼函式可能不需要比較所有結構成員來進行該判斷。例如，假設標識碼描述包含序號和一組硬體識別碼，如下所示：

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

在此情況下，EvtChildListIdentificationDescriptionCompare 回呼函式可能只需要比較 DeviceSerialNumber 成員，以判斷兩個描述是否代表相同的裝置。

如果您的驅動程式呼叫 WdfChildListRetrieveNextDevice 來周遊裝置清單，您可以提供額外的 EvtChildListIdentificationDescriptionCompare 回呼函式，架構在尋找要擷取的下一個描述時所使用的回呼函式。架構會尋找符合驅動程式提供 WDF_RETRIEVE_CHILD_FLAGS型別旗標的子裝置。如果驅動程式提供特殊的 EvtChildListIdentificationDescriptionCompare 回呼函式，架構會使用回調函式來精簡搜尋。如果驅動程式未提供特殊的 EvtChildListIdentificationDescriptionCompare 回呼函式，架構會不會呼叫 RtlCompareMemory-- 它只會傳回符合指定旗標的每個子裝置。

驅動程式 EvtChildListIdentificationDescriptionCompare 回呼函式 WdfChildListGetDevice，唯一 framework 子清單物件方法。

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

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