Expand Minimize

WdfFdoRetrieveNextStaticChild method

[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

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

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft