EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE回调函数 (wdfchildlist.h)

项目
08/08/2023

[仅适用于 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 时提供的内存中。

如果每个说明由WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER结构的IdentificationDescriptionSize 成员指定，则框架可以使用 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 回调函数之前获取内部子列表对象锁。回调函数必须仅执行与比较操作相关的操作，例如调用框架内存对象方法和访问对象上下文空间。它不得调用访问其他驱动程序的方法。

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