WdfFdoRetrieveNextStaticChild function (wdffdo.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfFdoRetrieveNextStaticChild method retrieves a handle to the next framework device object in a list of child devices.

Syntax

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

Parameters

[in] Fdo

A handle to a framework device object that represents the parent device.

[in, optional] PreviousChild

A handle to a framework device object that represents the child device that was returned by a previous call to WdfFdoRetrieveNextStaticChild. For the first call to WdfFdoRetrieveNextStaticChild, this value must be NULL.

[in] Flags

A WDF_RETRIEVE_CHILD_FLAGS-typed enumerator value that identifies the type of child devices that the method should retrieve. This parameter cannot be zero.

Return value

If the operation succeeds, the method returns a handle to a framework device object. Otherwise it returns NULL.

A system bug check occurs if the driver supplies an invalid object handle.

Remarks

Bus drivers that use static bus enumeration can call WdfFdoRetrieveNextStaticChild.

To retrieve the items in a list of child devices, the driver should:

Call WdfFdoLockStaticChildListForIteration to lock the child list.
Repeatedly call WdfFdoRetrieveNextStaticChild to obtain the items in the list, one at a time, until the method returns NULL.
Call WdfFdoUnlockStaticChildListFromIteration to unlock the child list.

For more information about static child lists, see Enumerating the Devices on a Bus.

Examples

The following code example searches a static child list until it finds a child device with a serial number that matches a specific value. For other example uses of WdfFdoRetrieveNextStaticChild, see the Toaster sample bus driver.

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);

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdffdo.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf)