WdfChildListAddOrUpdateChildDescriptionAsPresent 函数（wdfchildlist.h）

项目
2025-02-07

[仅适用于 KMDF]

WdfChildListAddOrUpdateChildDescriptionAsPresent 方法向子级列表添加新子说明或更新现有子说明。

语法

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

参数

[in] ChildList

框架子列表对象的句柄。

[in] IdentificationDescription

指向标识子标识说明的 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 结构的指针。

[in, optional] AddressDescription

指向标识子地址说明的 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER 结构的指针。如果不需要地址说明，则可以将此参数 NULL。

返回值

WdfChildListAddOrUpdateChildDescriptionAsPresent 返回STATUS_SUCCESS，或者另一个 NTSTATUS 类型的状态值，NT_SUCCESS（status）等于 TRUE （如果作成功）。否则，此方法可能会返回以下值之一：

返回代码	描述
STATUS_INVALID_PARAMETER	输入参数无效。
STATUS_INVALID_DEVICE_REQUEST	标识说明或地址说明的大小不正确。
STATUS_OBJECT_NAME_EXISTS	已存在提供标识说明的子级。在这种情况下，框架会将提供的地址说明复制到现有子级。
STATUS_INSUFFICIENT_RESOURCES	可以分配子说明。

此方法也可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生系统 bug 检查。

言论

WdfChildListAddOrUpdateChildDescriptionAsPresent 方法搜索与提供的标识说明匹配的子项的指定子列表。如果找到匹配项，框架将更新子地址说明（如果已提供）并返回STATUS_OBJECT_NAME_EXISTS。如果未找到匹配项，框架将使用提供的标识和地址说明创建新的子级。

驱动程序可以调用 WdfChildListAddOrUpdateChildDescriptionAsPresent 添加或更新单个子说明。该框架会立即更新子列表，并通知即插即用（PnP）管理器已进行更改。

或者，驱动程序可以执行以下作：

调用 WdfChildListBeginScan 来准备要更新的子列表。
调用 WdfChildListAddOrUpdateChildDescriptionAsPresent 多次，以添加或更新所有父设备子级的子说明。
调用 WdfChildListEndScan 来处理对子列表的更改。

如果驱动程序使用此替代过程，框架将等到驱动程序调用 WdfChildListEndScan，然后更新子列表并通知 PnP 管理器已进行更改。当驱动程序调用 WdfChildListBeginScan时，框架会将以前报告的所有设备标记为不再存在。因此，驱动程序必须为所有子级调用 WdfChildListAddOrUpdateChildDescriptionAsPresent，而不仅仅是新发现的子级。

在驱动程序调用 WdfChildListAddOrUpdateChildDescriptionAsPresent之后，框架调用驱动程序的 EvtChildListCreateDevice 回调函数，以便驱动程序可以通过调用 WdfDeviceCreate来创建设备对象。

有关子列表的详细信息，请参阅动态枚举。

例子

以下代码示例基于 kmdf_fx2 示例包含的代码。该示例将子说明添加到设备的默认子列表中。它检索驱动程序以前存储在设备对象的上下文空间中的开关设置，然后针对设置的每个交换机调用 WdfChildListAddOrUpdateChildDescriptionAsPresent。

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.0
标头	wdfchildlist.h （包括 Wdf.h）
库	Wdf01000.sys（请参阅框架库版本控制。
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）