WdfChildListRetrieveNextDevice 函数 (wdfchildlist.h)
[仅适用于 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 的另一个状态值。 否则，此方法可能会返回以下值之一：
| 返回代码 | 说明 |
|---|---|
|
输入参数无效。 |
|
Iterator 指定的WDF_CHILD_LIST_ITERATOR结构的大小不正确 |
|
指定了地址说明，但子列表不包含地址说明。 |
|
框架到达子列表的末尾。 |
|
驱动程序未调用 WdfChildListBeginIteration。 |
此方法还可能返回其他 NTSTATUS 值。
如果驱动程序提供无效的对象句柄，则会发生系统 bug 检查。
注解
在调用 WdfChildListRetrieveNextDevice 之前，驱动程序必须调用 WdfChildListBeginIteration。 驱动程序完成遍历子列表后，必须调用 WdfChildListEndIteration。 然后，框架会通知即插即用 (PnP) 经理对子列表所做的任何更改。
每次驱动程序调用 WdfChildListRetrieveNextDevice 时，方法都会检索与以下搜索条件匹配的下一个子级：
- 子级的类型必须与驱动程序 WDF_CHILD_LIST_ITERATOR结构中的 WDF_RETRIEVE_CHILD_FLAGS 类型标志相对应。
- 如果驱动程序在其WDF_CHILD_RETRIEVE_INFO结构中提供指向 EvtChildListIdentificationDescriptionCompare 回调函数的指针，则回调函数必须返回 TRUE。
当 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) |
另请参阅
EvtChildListIdentificationDescriptionCompare