EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY回调函数 (wdfchildlist.h)

项目
02/26/2024

[仅适用于 KMDF]

驱动程序的 EvtChildListAddressDescriptionCopy 事件回调函数将子地址说明从一个指定位置复制到另一个指定位置。

语法

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

参数

[in] ChildList

框架子列表对象的句柄。

[in] SourceAddressDescription

指向 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 结构的指针，该结构标识子地址说明的源位置。

[out] DestinationAddressDescription

指向WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 结构的指针，该结构标识子地址说明的目标位置。

返回值

无

备注

如果总线驱动程序使用动态枚举，它可以通过调用 WdfFdoInitSetDefaultChildListConfig 或 WdfChildListCreate 来注册 EvtChildListAddressDescriptionCopy 回调函数。

当需要使用新信息更新现有说明，或者需要将地址说明的内容传递给驱动程序时，框架会将信息从驱动程序提供的地址说明复制到另一个地址说明。

EvtChildListAddressDescriptionCopy 回调函数必须将源说明的内容复制到目标说明。如果驱动程序的子设备需要地址说明，并且框架无法调用 RtlCopyMemory 来复制地址说明，则驱动程序必须提供此回调函数。 (如果说明包含指向其他内存的指针，则框架无法调用 RtlCopyMemory 。)

如果驱动程序提供地址说明，但未提供 EvtChildListAddressDescriptionCopy 回调函数，框架将通过调用 RtlCopyMemory 来复制地址说明。

以下步骤描述了一个典型方案：

驱动程序确定子设备是否存在。
驱动程序通过填写包含 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 结构的驱动程序定义结构，以及可能通过动态分配额外的内存来存储具有设备特定大小的地址信息来创建地址说明。
驱动程序调用 WdfChildListAddOrUpdateChildDescriptionAsPresent 来报告子设备，并提供指向地址说明的指针。
框架确定驱动程序之前已报告设备，因此框架可以使用新信息更新设备的旧地址说明。
框架调用 EvtChildListAddressDescriptionCopy 回调函数（如果存在） () 或 RtlCopyMemory 将新的地址说明信息复制到现有地址说明中。

如果说明包含由 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 结构的 AddressDescriptionSize 成员指定的具有预先确定大小的单个结构，则框架可以使用 RtlCopyMemory 复制地址说明。但是，有时说明还必须包含存储在动态分配的内存中的其他信息。在这种情况下，通常会定义说明结构，以便成员指向动态分配的内存，并且驱动程序必须提供 EvtChildListAddressDescriptionCopy 回调函数。回调函数必须执行以下操作：

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

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

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

如果驱动程序提供 EvtChildListAddressDescriptionCopy 回调函数，则它可能还需要 EvtChildListAddressDescriptionDuplicate 和 EvtChildListAddressDescriptionCleanup 回调函数。

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