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 管理員回報裝置是否存在，則為 。 否則，方法會傳回 NULL。 架構會在 WDF_CHILD_RETRIEVE_INFO 結構的 Status 成員中傳回其他狀態資訊。
如果驅動程式提供無效的物件句柄，就會發生系統錯誤檢查。
備註
在呼叫 WdfChildListRetrievePdo 之前，驅動程式必須將識別描述放在 WDF_CHILD_RETRIEVE_INFO 結構中。
WdfChildListRetrievePdo 方法會周遊指定的子清單，尋找標識符描述符合驅動程式在WDF_CHILD_RETRIEVE_INFO結構中提供的子系。 如果架構找到相符專案，而且子系有 位址描述，架構就會填入結構的位址描述。
請務必使用 WdfChildListBeginIteration 和 WdfChildListEndIteration 包裝此呼叫，以保護呼叫端免於在另一個線程上突然移除 PDO 的 PnP。
如需子清單的詳細資訊，請參閱 動態列舉。
範例
下列程式代碼範例會搜尋子清單，尋找標識符描述包含指定序號的子裝置，並取得代表子裝置之裝置物件的句柄。
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);
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 最低 KMDF 版本 | 1.0 |
| 標頭 | wdfchildlist.h (包含 Wdf.h) |
| 程式庫 | Wdf01000.sys (請參閱 Framework Library Versioning.) |
| IRQL | <= DISPATCH_LEVEL |
| DDI 合規性規則 | DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) |