WdfChildListRetrieveNextDevice 函数 (wdfchildlist.h)

项目
08/08/2023

[仅适用于 KMDF]

WdfChildListRetrieveNextDevice 方法遍历指定的子列表，并检索与指定条件匹配的下一个子设备。

语法

NTSTATUS WdfChildListRetrieveNextDevice(
  [in]      WDFCHILDLIST             ChildList,
  [in]      PWDF_CHILD_LIST_ITERATOR Iterator,
  [out]     WDFDEVICE                *Device,
  [in, out] PWDF_CHILD_RETRIEVE_INFO Info
);

参数

[in] ChildList

框架子列表对象的句柄。

[in] Iterator

指向驱动程序之前提供给 WdfChildListBeginIteration 的同一调用方分配WDF_CHILD_LIST_ITERATOR结构的指针。

[out] Device

指向接收框架设备对象的句柄的位置的指针。如果 Iterator 参数指定 WdfRetrievePendingChildren 标志，则收到的值为 NULL。

[in, out] Info

指向调用方分配的WDF_CHILD_RETRIEVE_INFO 结构的指针。此指针是可选的，可以为 NULL。

返回值

如果操作成功，WdfChildListRetrieveNextDevice 将返回STATUS_SUCCESS或NT_SUCCESS (状态) 等于 TRUE 的另一个状态值。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_PARAMETER	输入参数无效。
STATUS_INFO_LENGTH_MISMATCH	Iterator 指定的WDF_CHILD_LIST_ITERATOR结构的大小不正确
STATUS_INVALID_DEVICE_REQUEST	指定了地址说明，但子列表不包含地址说明。
STATUS_NO_MORE_ENTRIES	框架到达子列表的末尾。
STATUS_INVALID_DEVICE_STATE	驱动程序未调用 WdfChildListBeginIteration。

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

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

注解

在调用 WdfChildListRetrieveNextDevice 之前，驱动程序必须调用 WdfChildListBeginIteration。驱动程序完成遍历子列表后，必须调用 WdfChildListEndIteration。然后，框架会通知即插即用 (PnP) 经理对子列表所做的任何更改。

每次驱动程序调用 WdfChildListRetrieveNextDevice 时，方法都会检索与以下搜索条件匹配的下一个子级：

子级的类型必须与驱动程序 WDF_CHILD_LIST_ITERATOR结构中的 WDF_RETRIEVE_CHILD_FLAGS 类型标志相对应。
如果驱动程序在其WDF_CHILD_RETRIEVE_INFO结构中提供指向 EvtChildListIdentificationDescriptionCompare 回调函数的指针，则回调函数必须返回 TRUE。

如果驱动程序提供 EvtChildListIdentificationDescriptionCompare 回调函数，则它还必须在 WDF_CHILD_RETRIEVE_INFO 结构中提供标识说明。如果WDF_RETRIEVE_CHILD_FLAGS类型的标志指示子项是匹配候选项，框架使用回调函数将传入的标识描述符与子列表中的子项说明进行比较。如果回调函数返回 TRUE，则表示匹配成功。如果回调函数返回 FALSE，框架会查找另一个候选项。

当 WdfChildListRetrieveNextDevice 找到匹配项时，如果 Info 参数指定的指针不是 NULL，则会将子级的标识说明和地址说明复制到驱动程序的WDF_CHILD_RETRIEVE_INFO结构中。 (请注意，此操作将覆盖驱动程序的输入标识说明。) 方法还会在 Device 参数标识的位置中放置子设备对象的句柄。

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

示例

下面的代码示例通知框架，将弹出父设备的所有子级。该示例获取设备的默认子列表并演练该列表。它获取每个子级的标识描述符，并将每个标识描述符传递给 WdfChildListRequestChildEject。

WDF_CHILD_LIST_ITERATOR  iterator;
WDFDEVICE  hChild;
NTSTATUS  status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST  list;
WDF_CHILD_RETRIEVE_INFO  childInfo;
PDO_IDENTIFICATION_DESCRIPTION  description;
BOOLEAN  ret;

list = WdfFdoGetDefaultChildList(Device);

WDF_CHILD_LIST_ITERATOR_INIT(
                             &iterator,
                             WdfRetrievePresentChildren
                             );
WdfChildListBeginIteration(
                           list,
                           &iterator
                           );
for (;;) {
    WDF_CHILD_RETRIEVE_INFO_INIT(
                                 &childInfo,
                                 &description.Header
                                 );
    WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                     &description.Header,
                                                     sizeof(description)
                                                     );
    status = WdfChildListRetrieveNextDevice(
                                            list, 
                                            &iterator, 
                                            &hChild, 
                                            &childInfo
                                            );
    if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
       break;
    }
    ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);

    ret = WdfChildListRequestChildEject(
                                        list,
                                        &description.Header
                                        );
    if(!ret) {
       WDFVERIFY(ret);
    }
}
WdfChildListEndIteration(
                         list,
                         &iterator
                         );
if (status == STATUS_NO_MORE_ENTRIES) {
   status = STATUS_SUCCESS;
}
return status;

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
标头	wdfchildlist.h (包括 Wdf.h)
Library	Wdf01000.sys (请参阅框架库版本控制.)
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)