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。否则，此函数必须返回 FALSE。

言论

如果总线驱动程序使用动态枚举，则可以通过调用 WdfFdoInitSetDefaultChildListConfig 或 WdfChildListCreate来注册 EvtChildListIdentificationDescriptionCompare 回调函数。驱动程序还可以在调用 WdfChildListRetrieveNextDevice时注册第二个特殊情况 EvtChildListIdentificationDescriptionCompare 回调函数。

当框架必须确定这两个说明是否识别同一设备时，框架将比较两个标识说明。

EvtChildListIdentificationDescriptionCompare 回调函数必须比较两个标识说明的内容，并返回 TRUE（如果匹配）。如果框架无法调用 RtlCompareMemory 来比较标识说明，驱动程序必须提供此回调函数。（如果说明包含指向其他内存的指针，则框架无法调用 RtlCompareMemory。

如果驱动程序不提供 EvtChildListIdentificationDescriptionCompare 回调函数，则框架会通过调用 RtlCompareMemory来比较标识说明。

以下步骤描述了一个可能的方案：

驱动程序调用 WdfChildListRetrieveAddressDescription 以获取与框架的标识说明副本（存储在子列表中）关联的地址说明。
框架遍历子列表。若要确定子项的标识说明是否与驱动程序在调用 WdfChildListRetrieveAddressDescription时指定的标识说明匹配，框架将调用 EvtChildListIdentificationDescriptionCompare 回调函数（如果存在），或 RtlCompareMemory。
如果两个标识说明匹配（并且比较返回 TRUE），框架将停止遍历列表。
框架将地址说明复制到驱动程序在调用 WdfChildListRetrieveAddressDescription时提供的内存中。

如果每个描述包含由 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADERIdentificationDescriptionSize 成员指定的预定义大小，则框架可以使用 RtlCompareMemory 来比较标识说明。但是，有时说明还必须包含存储在动态分配内存中的其他信息。在这种情况下，通常会定义说明结构，以便成员指向动态分配的内存，并且驱动程序必须提供 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 回调函数之前获取内部子列表对象锁。回调函数只能执行与比较作相关的作，例如调用框架内存对象方法和访问对象上下文空间。它不得调用访问其他驱动程序的方法。

有关动态枚举的详细信息，请参阅枚举总线上的设备。