WdfChildListRetrieveNextDevice 函式 (wdfchildlist.h)

發行項
03/05/2024

[僅適用於 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
STATUS_INVALID_PARAMETER	輸入參數無效。
STATUS_INFO_LENGTH_MISMATCH	Iterator 指定的WDF_CHILD_LIST_ITERATOR結構大小不正確
STATUS_INVALID_DEVICE_REQUEST	已指定位址描述，但子清單未包含位址描述。
STATUS_NO_MORE_ENTRIES	架構已到達子清單的結尾。
STATUS_INVALID_DEVICE_STATE	驅動程式尚未呼叫 WdfChildListBeginIteration。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生系統錯誤檢查。

備註

在呼叫 WdfChildListRetrieveNextDevice 之前，您的驅動程式必須呼叫 WdfChildListBeginIteration。在驅動程式完成周遊子清單之後，它必須呼叫 WdfChildListEndIteration。架構接著會通知隨插即用 (PnP) 管理員對子清單所做的任何變更。

每次驅動程式呼叫 WdfChildListRetrieveNextDevice 時，方法都會擷取符合下列搜尋準則的下一個子系：

子系的類型必須對應至驅動程式WDF_CHILD_LIST_ITERATOR結構中的WDF_RETRIEVE_CHILD_FLAGS型別旗標。
如果驅動程式在其WDF_CHILD_RETRIEVE_INFO結構中提供 EvtChildListIdentificationDescriptionCompare 回呼函式的指標，回呼函式必須傳回 TRUE。

如果驅動程式提供 EvtChildListIdentificationDescriptionCompare 回呼函式，它也必須在WDF_CHILD_RETRIEVE_INFO結構中提供識別描述。如果WDF_RETRIEVE_CHILD_FLAGS型別旗標指出子系是相符的候選專案，架構會使用回呼函式來比較傳入的識別描述元與子清單中的子描述。如果回呼函式傳回 TRUE，則比對成功。如果回呼函式傳回 FALSE，架構會尋找另一個候選專案。

當 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)