WdfChildListRetrieveNextDevice-Funktion (wdfchildlist.h)

Artikel
02/26/2024

[Gilt nur für KMDF]

Die WdfChildListRetrieveNextDevice-Methode durchläuft eine angegebene untergeordnete Liste und ruft das nächste untergeordnete Gerät ab, das den angegebenen Kriterien entspricht.

Syntax

NTSTATUS WdfChildListRetrieveNextDevice(
  [in]      WDFCHILDLIST             ChildList,
  [in]      PWDF_CHILD_LIST_ITERATOR Iterator,
  [out]     WDFDEVICE                *Device,
  [in, out] PWDF_CHILD_RETRIEVE_INFO Info
);

Parameter

[in] ChildList

Ein Handle für ein Frameworkobjekt mit untergeordneter Liste.

[in] Iterator

Ein Zeiger auf dieselbe vom Aufrufer zugewiesene WDF_CHILD_LIST_ITERATOR Struktur, die der Treiber zuvor für WdfChildListBeginIteration bereitgestellt hat.

[out] Device

Ein Zeiger auf eine Position, die ein Handle für ein Frameworkgeräteobjekt empfängt. Der empfangene Wert ist NULL , wenn der Iterator-Parameter das WdfRetrievePendingChildren-Flag angibt.

[in, out] Info

Ein Zeiger auf eine aufruferseitig zugeordnete WDF_CHILD_RETRIEVE_INFO-Struktur . Dieser Zeiger ist optional und kann NULL sein.

Rückgabewert

WdfChildListRetrieveNextDevice gibt STATUS_SUCCESS oder einen anderen status Wert zurück, für den NT_SUCCESS(status)true entspricht, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein Eingabeparameter war ungültig.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_CHILD_LIST_ITERATOR Struktur, die von Iterator angegeben wurde, war falsch.
STATUS_INVALID_DEVICE_REQUEST	Es wurde eine Adressbeschreibung angegeben, aber die untergeordnete Liste enthielt keine Adressbeschreibungen.
STATUS_NO_MORE_ENTRIES	Das Framework hat das Ende der untergeordneten Liste erreicht.
STATUS_INVALID_DEVICE_STATE	Der Treiber hat nicht WdfChildListBeginIteration aufgerufen.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Systemfehlerprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Bevor Sie WdfChildListRetrieveNextDevice aufrufen, muss Ihr Treiber WdfChildListBeginIteration aufrufen. Nachdem der Treiber die untergeordnete Liste durchlaufen hat, muss er WdfChildListEndIteration aufrufen. Das Framework informiert dann den Plug & Play-Manager (PnP) über alle Änderungen, die an der untergeordneten Liste vorgenommen wurden.

Jedes Mal, wenn der Treiber WdfChildListRetrieveNextDevice aufruft, ruft die -Methode das nächste untergeordnete Element ab, das den folgenden Suchkriterien entspricht:

Der Typ des untergeordneten Elements muss WDF_RETRIEVE_CHILD_FLAGS typisierten Flags in der WDF_CHILD_LIST_ITERATOR Struktur des Treibers entsprechen.
Wenn der Treiber einen Zeiger auf eine EvtChildListIdentificationDescriptionCompare-Rückruffunktion in seiner WDF_CHILD_RETRIEVE_INFO-Struktur bereitstellt, muss die Rückruffunktion TRUE zurückgeben.

Wenn der Treiber eine EvtChildListIdentificationDescriptionCompare-Rückruffunktion bereitstellt, muss er auch eine Identifikationsbeschreibung in der WDF_CHILD_RETRIEVE_INFO-Struktur bereitstellen. Das Framework verwendet die Rückruffunktion, um den übergebenen Identifikationsdeskriptor mit der Beschreibung eines untergeordneten Elements in der untergeordneten Liste zu vergleichen, wenn die WDF_RETRIEVE_CHILD_FLAGS-typisierten Flags angeben, dass das untergeordnete Element ein Übereinstimmungskandidat ist. Wenn die Rückruffunktion TRUE zurückgibt, ist die Übereinstimmung erfolgreich. Wenn die Rückruffunktion FALSE zurückgibt, sucht das Framework nach einem anderen Kandidaten.

Wenn WdfChildListRetrieveNextDevice eine Übereinstimmung findet, kopiert es die Identifikations- und Adressbeschreibung des Untergeordneten in die WDF_CHILD_RETRIEVE_INFO-Struktur des Treibers, wenn der zeiger, den der Info-Parameter angibt, nicht NULL ist. (Beachten Sie, dass dieser Vorgang die Beschreibung der Eingabeidentifikation des Treibers überschreibt.) Die -Methode platziert auch ein Handle für das untergeordnete Geräteobjekt an der Position, die der Device-Parameter identifiziert.

Weitere Informationen zu untergeordneten Listen finden Sie unter Dynamische Enumeration.

Beispiele

Im folgenden Codebeispiel wird das Framework darüber informiert, dass alle untergeordneten Elemente eines übergeordneten Geräts ausgeworfen werden. Das Beispiel ruft die untergeordnete Standardliste eines Geräts ab und führt die Liste durch. Es ruft den Identifikationsdeskriptor jedes Untergeordneten ab und übergibt jeden Identifikationsdeskriptor an 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;

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfchildlist.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)