WdfFdoRetrieveNextStaticChild function (wdffdo.h)

[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(
  WDFDEVICE Fdo,
  WDFDEVICE PreviousChild,
  ULONG     Flags
);

Parameters

Fdo

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

PreviousChild

[in, optional] 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.

Flags

[in] 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:

  1. Call WdfFdoLockStaticChildListForIteration to lock the child list.
  2. Repeatedly call WdfFdoRetrieveNextStaticChild to obtain the items in the list, one at a time, until the method returns NULL.
  3. 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

   
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, KmdfIrql, KmdfIrql2, PdoDeviceInitAPI

See also

WdfFdoLockStaticChildListForIteration

WdfFdoUnlockStaticChildListFromIteration