WdfChildListRetrievePdo-Funktion (wdfchildlist.h)
[Gilt nur für KMDF]
Die WdfChildListRetrievePdo--Methode gibt ein Handle an das Framework-Geräteobjekt zurück, das einer angegebenen untergeordneten Beschreibung in einer untergeordneten Liste zugeordnet ist.
Syntax
WDFDEVICE WdfChildListRetrievePdo(
[in] WDFCHILDLIST ChildList,
[in, out] PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
);
Parameter
[in] ChildList
Ein Handle zu einem untergeordneten Listenobjekt.
[in, out] RetrieveInfo
Ein Zeiger auf eine vom Treiber zugewiesene WDF_CHILD_RETRIEVE_INFO Struktur, die der Treiber mit der Identifikationsbeschreibung initialisiert, des abzurufenden untergeordneten Elements.
Rückgabewert
WdfChildListRetrievePdo gibt ein Handle an das Framework-Geräteobjekt zurück, wenn sich das angegebene untergeordnete Gerät in der untergeordneten Liste befindet, wenn ein Framework-Geräteobjekt für das untergeordnete Gerät vorhanden ist und wenn das Framework das Vorhandensein des Geräts an den PnP-Manager gemeldet hat. Andernfalls gibt die Methode NULL-zurück. Das Framework gibt zusätzliche Statusinformationen im Status Member der WDF_CHILD_RETRIEVE_INFO-Struktur zurück.
Eine Systemfehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Bemerkungen
Vor dem Aufrufen WdfChildListRetrievePdo-muss der Treiber eine Identifikationsbeschreibung in einer WDF_CHILD_RETRIEVE_INFO Struktur platzieren.
Die WdfChildListRetrievePdo Methode durchläuft die angegebene untergeordnete Liste und sucht nach einem untergeordneten Element mit einer Identifikationsbeschreibung, die dem in der WDF_CHILD_RETRIEVE_INFO-Struktur angegebenen Treiber entspricht. Wenn das Framework eine Übereinstimmung findet und das untergeordnete Element über eine Adressbeschreibungverfügt, füllt das Framework die Adressbeschreibung der Struktur aus.
Schließen Sie diesen Aufruf unbedingt mit WdfChildListBeginIteration und WdfChildListEndIteration, um den Aufrufer vor plötzlicher PnP-Entfernung des PDO in einem anderen Thread zu schützen.
Weitere Informationen zu untergeordneten Listen finden Sie unter dynamische Enumeration.
Beispiele
Im folgenden Codebeispiel wird eine untergeordnete Liste durchsucht, um ein untergeordnetes Gerät zu finden, dessen Identifikationsbeschreibung eine angegebene Seriennummer enthält, und es erhält ein Handle für das Geräteobjekt, das das untergeordnete Gerät darstellt.
WDF_CHILD_LIST_ITERATOR iterator;
PDO_IDENTIFICATION_DESCRIPTION description;
WDF_CHILD_RETRIEVE_INFO info;
WDFDEVICE hChild;
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
&description.Header,
sizeof(description)
);
description.SerialNo = DeviceSerialNumber;
WDF_CHILD_RETRIEVE_INFO_INIT(
&info,
&description.Header
);
WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);
WdfChildListBeginIteration(childList, &iterator);
hChild = WdfChildListRetrievePdo(
childList,
&info
);
... access hChild ...
WdfChildListEndIteration(childList, &iterator);
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) |