WdfChildListRetrieveNextDevice function (wdfchildlist.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfChildListRetrieveNextDevice method traverses a specified child list and retrieves the next child device that matches specified criteria.

Syntax

NTSTATUS WdfChildListRetrieveNextDevice(
  [in]      WDFCHILDLIST             ChildList,
  [in]      PWDF_CHILD_LIST_ITERATOR Iterator,
  [out]     WDFDEVICE                *Device,
  [in, out] PWDF_CHILD_RETRIEVE_INFO Info
);

Parameters

[in] ChildList

A handle to a framework child-list object.

[in] Iterator

A pointer to the same caller-allocated WDF_CHILD_LIST_ITERATOR structure that the driver previously supplied to WdfChildListBeginIteration.

[out] Device

A pointer to a location that receives a handle to a framework device object. The received value is NULL if the Iterator parameter specifies the WdfRetrievePendingChildren flag.

[in, out] Info

A pointer to a caller-allocated WDF_CHILD_RETRIEVE_INFO structure. This pointer is optional and can be NULL.

Return value

WdfChildListRetrieveNextDevice returns STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE, if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter was invalid.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_CHILD_LIST_ITERATOR structure that Iterator specified was incorrect
STATUS_INVALID_DEVICE_REQUEST	An address description was specified but the child list did not contain address descriptions.
STATUS_NO_MORE_ENTRIES	The framework reached the end of the child list.
STATUS_INVALID_DEVICE_STATE	The driver has not called WdfChildListBeginIteration.

This method might also return other NTSTATUS values.

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

Remarks

Before calling WdfChildListRetrieveNextDevice, your driver must call WdfChildListBeginIteration. After the driver has finished traversing the child list, it must call WdfChildListEndIteration. The framework then informs the Plug and Play (PnP) manager of any changes that were made to the child list.

Each time the driver calls WdfChildListRetrieveNextDevice, the method retrieves the next child that matches the following search criteria:

The child's type must correspond to WDF_RETRIEVE_CHILD_FLAGS-typed flags in the driver's WDF_CHILD_LIST_ITERATOR structure.
If the driver provides a pointer to an EvtChildListIdentificationDescriptionCompare callback function in its WDF_CHILD_RETRIEVE_INFO structure, the callback function must return TRUE.

If the driver provides an EvtChildListIdentificationDescriptionCompare callback function, it must also provide an identification description in the WDF_CHILD_RETRIEVE_INFO structure. The framework uses the callback function to compare the passed-in identification descriptor with a child's description in the child list, if the WDF_RETRIEVE_CHILD_FLAGS-typed flags indicate that the child is a match candidate. If the callback function returns TRUE, the match is successful. If the callback function returns FALSE, the framework looks for another candidate.

When WdfChildListRetrieveNextDevice finds a match, it copies the child's identification description and address description into the driver's WDF_CHILD_RETRIEVE_INFO structure, if the pointer that the Info parameter specifies is not NULL. (Note that this operation overwrites the driver's input identification description.) The method also places a handle to the child's device object in the location that the Device parameter identifies.

For more information about child lists, see Dynamic Enumeration.

Examples

The following code example informs the framework that all of a parent device's children are being ejected. The example obtains a device's default child list and walks through the list. It obtains each child's identification descriptor, and it passes each identification descriptor to WdfChildListRequestChildEject.

WDF_CHILD_LIST_ITERATOR  iterator;
WDFDEVICE  hChild;
NTSTATUS  status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST  list;
WDF_CHILD_RETRIEVE_INFO  childInfo;
PDO_IDENTIFICATION_DESCRIPTION  description;
BOOLEAN  ret;

list = WdfFdoGetDefaultChildList(Device);

WDF_CHILD_LIST_ITERATOR_INIT(
                             &iterator,
                             WdfRetrievePresentChildren
                             );
WdfChildListBeginIteration(
                           list,
                           &iterator
                           );
for (;;) {
    WDF_CHILD_RETRIEVE_INFO_INIT(
                                 &childInfo,
                                 &description.Header
                                 );
    WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                     &description.Header,
                                                     sizeof(description)
                                                     );
    status = WdfChildListRetrieveNextDevice(
                                            list, 
                                            &iterator, 
                                            &hChild, 
                                            &childInfo
                                            );
    if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
       break;
    }
    ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);

    ret = WdfChildListRequestChildEject(
                                        list,
                                        &description.Header
                                        );
    if(!ret) {
       WDFVERIFY(ret);
    }
}
WdfChildListEndIteration(
                         list,
                         &iterator
                         );
if (status == STATUS_NO_MORE_ENTRIES) {
   status = STATUS_SUCCESS;
}
return status;

Requirements

Requirement	Value
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(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via