WdfChildListRetrievePdo 函数 （wdfchildlist.h）
[仅适用于 KMDF]
WdfChildListRetrievePdo 方法将句柄返回到与子列表中的指定子说明关联的框架设备对象。
语法
WDFDEVICE WdfChildListRetrievePdo(
[in] WDFCHILDLIST ChildList,
[in, out] PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
);
参数
[in] ChildList
子列表对象的句柄。
[in, out] RetrieveInfo
指向驱动程序分配的 WDF_CHILD_RETRIEVE_INFO 结构的指针，驱动程序使用要检索的子 标识说明进行初始化。
返回值
WdfChildListRetrievePdo 如果指定的子设备位于子列表中，如果子设备存在框架设备对象，并且框架已向 PnP 管理器报告设备是否存在，则 WdfChildListRetrievePdo 将返回框架设备对象的句柄。 否则，该方法将返回 NULL 。 框架在 WDF_CHILD_RETRIEVE_INFO 结构的 状态 成员中返回其他状态信息。
如果驱动程序提供无效的对象句柄，则会发生系统 bug 检查。
言论
在调用 WdfChildListRetrievePdo之前，驱动程序必须在 WDF_CHILD_RETRIEVE_INFO 结构中放置标识说明。
WdfChildListRetrievePdo 方法遍历指定的子列表，查找具有标识说明的子级，该说明与驱动程序在WDF_CHILD_RETRIEVE_INFO结构中提供的子列表匹配。 如果框架找到匹配项，并且子级具有 地址说明，则框架将填写结构的地址说明。
请务必将此调用包装在 WdfChildListBeginIteration 和 WdfChildListEndIteration，以防止调用方在另一个线程上突然删除 PDO。
有关子列表的详细信息，请参阅 动态枚举。
例子
下面的代码示例搜索子列表以查找标识说明包含指定序列号的子设备，并获取表示子设备的设备对象的句柄。
WDF_CHILD_LIST_ITERATOR iterator;
PDO_IDENTIFICATION_DESCRIPTION description;
WDF_CHILD_RETRIEVE_INFO info;
WDFDEVICE hChild;
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
&description.Header,
sizeof(description)
);
description.SerialNo = DeviceSerialNumber;
WDF_CHILD_RETRIEVE_INFO_INIT(
&info,
&description.Header
);
WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);
WdfChildListBeginIteration(childList, &iterator);
hChild = WdfChildListRetrievePdo(
childList,
&info
);
... access hChild ...
WdfChildListEndIteration(childList, &iterator);
要求
| 要求 | 价值 |
|---|---|
| 目标平台 | 普遍 |
| 最低 KMDF 版本 | 1.0 |
| 标头 | wdfchildlist.h （包括 Wdf.h） |
| 库 | Wdf01000.sys（请参阅框架库版本控制。 |
| IRQL | <= DISPATCH_LEVEL |
| DDI 符合性规则 | DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf） |