EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE回呼函式 (wdfchildlist.h)

發行項
03/01/2024

[僅適用於 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 。否則，此函式必須傳回 FALSE。

備註

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

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

EvtChildListIdentificationDescriptionCompare 回呼函式必須比較兩個識別描述的內容，如果相符，則會傳回 TRUE。如果架構無法呼叫 RtlCompareMemory 來比較識別描述，驅動程式必須提供此回呼函式。 (如果描述包含其他 memory 的指標，架構就無法呼叫 RtlCompareMemory 。)

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

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

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

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

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

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