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 结构的指针，该结构由驱动程序使用要检索的子级的 标识说明 进行初始化。

返回值

如果指定的子设备位于子列表中，如果子设备存在框架设备对象，并且框架已向 PnP 管理器报告设备存在，则 WdfChildListRetrievePdo 将返回框架设备对象的句柄。 否则，方法返回 NULL。 框架在 WDF_CHILD_RETRIEVE_INFO 结构的 Status 成员中返回其他状态信息。

如果驱动程序提供无效的对象句柄，则会发生系统 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)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL <= DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_CHILD_RETRIEVE_INFO_INIT