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 的另一個狀態值。 否則，這個方法可能會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
|
輸入參數無效。 |
|
Iterator 指定的WDF_CHILD_LIST_ITERATOR結構大小不正確 |
|
已指定位址描述，但子清單未包含位址描述。 |
|
架構已到達子清單的結尾。 |
|
驅動程式尚未呼叫 WdfChildListBeginIteration。 |
這個方法也可能傳回其他 NTSTATUS值。
如果驅動程式提供無效的物件句柄，就會發生系統錯誤檢查。
備註
在呼叫 WdfChildListRetrieveNextDevice 之前，您的驅動程式必須呼叫 WdfChildListBeginIteration。 在驅動程式完成周遊子清單之後，它必須呼叫 WdfChildListEndIteration。 架構接著會通知 隨插即用 (PnP) 管理員對子清單所做的任何變更。
每次驅動程式呼叫 WdfChildListRetrieveNextDevice 時，方法都會擷取符合下列搜尋準則的下一個子系：
- 子系的類型必須對應至驅動程式WDF_CHILD_LIST_ITERATOR結構中的WDF_RETRIEVE_CHILD_FLAGS型別旗標。
- 如果驅動程式在其WDF_CHILD_RETRIEVE_INFO結構中提供 EvtChildListIdentificationDescriptionCompare 回呼函式的指標，回呼函式必須傳回 TRUE。
當 WdfChildListRetrieveNextDevice 找到相符專案時，它會將子系的識別描述和位址描述複製到驅動程式 的WDF_CHILD_RETRIEVE_INFO 結構，如果 Info 參數指定的指標不是 NULL。 (請注意，此作業會覆寫驅動程式的輸入識別描述。) 方法也會將句柄放在 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;
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | 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) |
另請參閱
EvtChildListIdentificationDescriptionCompare