EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY回调函数（wdfchildlist.h）

2025-02-07

[仅适用于 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结构中分配和标识的内存。

如果描述包含由 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 结构的 IdentificationDescriptionSize 成员指定的单个结构，则框架可以使用 RtlCopyMemory 复制标识说明。但是，有时说明还必须包含存储在动态分配内存中的其他信息。在这种情况下，通常会定义说明结构，以便成员指向动态分配的内存，并且驱动程序必须提供 EvtChildListIdentificationDescriptionCopy 回调函数。回调函数必须执行以下作：

在回调函数的 SourceIdentificationDescription 和 DestinationIdentificationDescription 结构中，找到用于动态分配内存的指针。
使用指针将动态分配的内存从源复制到目标。
将回调函数的 SourceIdentificationDescription 结构中的其他结构成员复制到回调函数的 DestinationIdentificationDescription 结构。

驱动程序 EvtChildListIdentificationDescriptionCopy 回调函数调用的唯一 框架子列表对象 方法是 WdfChildListGetDevice。

框架在调用 EvtChildListIdentificationDescriptionCopy 回调函数之前获取内部子列表对象锁。回调函数只能执行与复制作相关的作，例如调用框架内存对象方法和访问对象上下文空间。它不得调用访问其他驱动程序的方法。

如果驱动程序提供 EvtChildListIdentificationDescriptionCopy 回调函数，则它可能需要 EvtChildListIdentificationDuplicate、EvtChildListIdentificationDescriptionCompare和 EvtChildListIdentificationDescriptionCleanup 回调函数。

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