WdfFdoRetrieveNextStaticChild-Funktion (wdffdo.h)

Artikel
03/01/2024

[Gilt nur für KMDF]

Die WdfFdoRetrieveNextStaticChild-Methode ruft ein Handle für das nächste Framework-Geräteobjekt in einer Liste der untergeordneten Geräte ab.

Syntax

WDFDEVICE WdfFdoRetrieveNextStaticChild(
  [in]           WDFDEVICE Fdo,
  [in, optional] WDFDEVICE PreviousChild,
  [in]           ULONG     Flags
);

Parameter

[in] Fdo

Ein Handle für ein Frameworkgeräteobjekt, das das übergeordnete Gerät darstellt.

[in, optional] PreviousChild

Ein Handle für ein Frameworkgeräteobjekt, das das untergeordnete Gerät darstellt, das von einem vorherigen Aufruf von WdfFdoRetrieveNextStaticChild zurückgegeben wurde. Für den ersten Aufruf von WdfFdoRetrieveNextStaticChild muss dieser Wert NULL sein.

[in] Flags

Ein WDF_RETRIEVE_CHILD_FLAGS typisierter Enumeratorwert, der den Typ der untergeordneten Geräte angibt, den die Methode abrufen soll. Dieser Parameter darf nicht 0 sein.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Methode ein Handle an ein Frameworkgeräteobjekt zurück. Andernfalls wird NULL zurückgegeben.

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

Hinweise

Bustreiber, die eine statische Busaufzählung verwenden, können WdfFdoRetrieveNextStaticChild aufrufen.

Um die Elemente in einer Liste der untergeordneten Geräte abzurufen, muss der Treiber Folgendes ausführen:

Rufen Sie WdfFdoLockStaticChildListForIteration auf, um die untergeordnete Liste zu sperren.
Rufen Sie WdfFdoRetrieveNextStaticChild wiederholt auf, um die Elemente in der Liste einzeln abzurufen, bis die Methode NULL zurückgibt.
Rufen Sie WdfFdoUnlockStaticChildListFromIteration auf, um die untergeordnete Liste zu entsperren.

Weitere Informationen zu statischen untergeordneten Listen finden Sie unter Auflisten der Geräte auf einem Bus.

Beispiele

Im folgenden Codebeispiel wird eine statische untergeordnete Liste durchsucht, bis ein untergeordnetes Gerät mit einer Seriennummer gefunden wird, die einem bestimmten Wert entspricht. Weitere Beispielverwendungen von WdfFdoRetrieveNextStaticChild finden Sie im Toaster-Beispielbustreiber.

PPDO_DEVICE_DATA  pdoData;
WDFDEVICE  hChild;
NTSTATUS  status = STATUS_INVALID_PARAMETER;

WdfFdoLockStaticChildListForIteration(Device);

while ((hChild = WdfFdoRetrieveNextStaticChild(
                                               Device,
                                               hChild,
                                               WdfRetrieveAddedChildren
                                               )) != NULL) {
    //
    // Obtain device object context data and check the
    // stored serial number.
    //
    pdoData = PdoGetData(hChild);
    if (SerialNo == pdoData->SerialNo) {
        status = STATUS_SUCCESS;
        WdfPdoRequestEject(hChild);
        break;
    }
}
WdfFdoUnlockStaticChildListFromIteration(Device);

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdffdo.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), PdoDeviceInitAPI(kmdf)

Weitere Informationen

WdfFdoLockStaticChildListForIteration

WdfFdoUnlockStaticChildListFromIteration

Freigeben über