WdfChildListRetrievePdo method

[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

ChildList [in]

A handle to a child list object.

RetrieveInfo [in, out]

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.

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.


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

hChild = WdfChildListRetrievePdo(
                                 list,
                                 &info
                                 );

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Header

Wdfchildlist.h (include Wdf.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT
WDF_CHILD_RETRIEVE_INFO
WDF_CHILD_RETRIEVE_INFO_INIT

 

 

Send comments about this topic to Microsoft

Show: