WdfChildListRetrievePdo-Funktion (wdfchildlist.h)
[Gilt nur für KMDF]
Die WdfChildListRetrievePdo-Methode gibt ein Handle für 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 für ein untergeordnetes Listenobjekt.
[in, out] RetrieveInfo
Ein Zeiger auf eine vom Treiber zugewiesene WDF_CHILD_RETRIEVE_INFO Struktur, die der Treiber mit der Identifikationsbeschreibung des abzurufenden untergeordneten Elements initialisiert.
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 Frameworkgeräteobjekt für das untergeordnete Gerät vorhanden ist und das Framework die Existenz des Geräts an den PnP-Manager gemeldet hat. Andernfalls gibt die Methode NULL zurück. Das Framework gibt zusätzliche status Informationen im Statuselement der WDF_CHILD_RETRIEVE_INFO-Struktur zurück.
Eine Systemfehlerprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Vor dem Aufrufen von 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 der vom Treiber in der WDF_CHILD_RETRIEVE_INFO-Struktur angegebenen Entspricht. Wenn das Framework eine Übereinstimmung findet und das untergeordnete Element über eine Adressbeschreibung verfügt, füllt das Framework die Adressbeschreibung der Struktur aus.
Stellen Sie sicher, dass Sie diesen Aufruf mit WdfChildListBeginIteration und WdfChildListEndIteration umschließen , um den Aufrufer vor der plötzlichen PnP-Entfernung des PDO in einem anderen Thread zu schützen.
Weitere Informationen zu untergeordneten Listen finden Sie unter Dynamische Enumeration.
Beispiele
Das folgende Codebeispiel durchsucht eine untergeordnete Liste, um ein untergeordnetes Gerät zu finden, dessen Identifikationsbeschreibung eine angegebene Seriennummer enthält, und ruft ein Handle für das Geräteobjekt ab, 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 | 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) |