WdfChildListRetrievePdo function (wdfchildlist.h)

[Applies to KMDF only]

The WdfChildListRetrievePdo method returns a handle to the framework device object that is associated with a specified child description in a child list.

Syntax

WDFDEVICE WdfChildListRetrievePdo(
  [in]      WDFCHILDLIST             ChildList,
  [in, out] PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
);

Parameters

[in] ChildList

A handle to a child list object.

[in, out] RetrieveInfo

A pointer to a driver-allocated WDF_CHILD_RETRIEVE_INFO structure that the driver initializes with the identification description of the child to be retrieved.

Return value

WdfChildListRetrievePdo returns a handle to the framework device object if the specified child device is located in the child list, if a framework device object exists for the child device, and if the framework has reported the device's existence to the PnP manager. Otherwise, the method returns NULL. The framework returns additional status information in the Status member of the WDF_CHILD_RETRIEVE_INFO structure.

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

Remarks

Before calling WdfChildListRetrievePdo, the driver must place an identification description in a WDF_CHILD_RETRIEVE_INFO structure.

The WdfChildListRetrievePdo method traverses the specified child list, looking for a child with an identification description that matches the one that the driver supplied in the WDF_CHILD_RETRIEVE_INFO structure. If the framework finds a match, and if the child has an address description, the framework fills in the structure's address description.

Be sure to wrap this call with WdfChildListBeginIteration and WdfChildListEndIteration to protect the caller from sudden PnP removal of the PDO on another thread.

For more information about child lists, see Dynamic Enumeration.

Examples

The following code example searches a child list to find a child device whose identification description contains a specified serial number, and it obtains a handle to the device object that represents the child device.

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

Requirements

See also

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_CHILD_RETRIEVE_INFO_INIT