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（status）等於 true，則為另一個狀態值。 否則，此方法可能會傳回下列其中一個值：
| 傳回碼 | 描述 |
|---|---|
|
輸入參數無效。 |
|
反覆運算器 指定的 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;
要求
| 要求 | 價值 |
|---|---|
| 目標平臺 | 普遍 |
| 最低 KMDF 版本 | 1.0 |
| 標頭 | wdfchildlist.h （包括 Wdf.h） |
| 連結庫 | Wdf01000.sys （請參閱架構連結庫版本控制。） |
| IRQL | <= DISPATCH_LEVEL |
| DDI 合規性規則 | DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf） |
另請參閱
EvtChildListIdentificationDescriptionCompare