WdfChildListRetrieveNextDevice-Funktion (wdfchildlist.h)

Artikel
02/07/2025

[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 framework untergeordnetes Listenobjekt.

[in] Iterator

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

[out] Device

Ein Zeiger auf eine Position, die ein Handle zu einem Framework-Geräteobjekt empfängt. Der empfangene Wert ist NULL-, wenn der parameter Iterator den WdfRetrievePendingChildren Flag angibt.

[in, out] Info

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_CHILD_RETRIEVE_INFO Struktur. Dieser Zeiger ist optional und kann NULL-sein.

Rückgabewert

WdfChildListRetrieveNextDevice gibt STATUS_SUCCESS oder einen anderen Statuswert 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 angegebenen WDF_CHILD_LIST_ITERATOR Struktur, die 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 WdfChildListBeginIterationnicht aufgerufen.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

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

Bemerkungen

Vor dem Aufrufen WdfChildListRetrieveNextDevicemuss Ihr Treiber WdfChildListBeginIterationaufrufen. Nachdem der Treiber die untergeordnete Liste durchlaufen hat, muss er WdfChildListEndIterationaufrufen. Das Framework informiert dann den Plug and Play -Manager (PnP) über alle Änderungen, die an der untergeordneten Liste vorgenommen wurden.

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

Der Typ des untergeordneten Elements muss WDF_RETRIEVE_CHILD_FLAGS-typed flags in der WDF_CHILD_LIST_ITERATOR-Struktur des Treibers entsprechen.
Wenn der Treiber einen Zeiger auf eine EvtChildListIdentificationDescriptionCompare Rückruffunktion in der 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 Passed-In-Identifikationsdeskriptor mit der Beschreibung eines untergeordneten Elements in der untergeordneten Liste zu vergleichen, wenn die WDF_RETRIEVE_CHILD_FLAGS-Typ-Flags angeben, dass das untergeordnete Element ein Übereinstimmungskandidat ist. Wenn die Rückruffunktion TRUEzurü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 sie die Identifikationsbeschreibung 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 Eingabeidentifikationsbeschreibung des Treibers überschreibt.) Die Methode platziert außerdem ein Handle an der Position, an der der Device-Parameter identifiziert wird.

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 Standard-untergeordnete Liste eines Geräts ab und durchläuft die Liste. Es ruft die Identifikationsbeschreibung jedes Kindes 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-	Universal
Minimale KMDF-Version	1.0
Header-	wdfchildlist.h (include Wdf.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)