WdfChildListAddOrUpdateChildDescriptionAsPresent 函数 (wdfchildlist.h)

项目
08/08/2023

[仅适用于 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 (状态) 等于 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)
Library	Wdf01000.sys (请参阅框架库 Versioning.)
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)