WdfChildListRetrieveNextDevice function (wdfchildlist.h)

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

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)

See also

EvtChildListIdentificationDescriptionCompare

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_LIST_ITERATOR

WDF_CHILD_LIST_ITERATOR_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_RETRIEVE_CHILD_FLAGS

WdfChildListBeginIteration

WdfChildListBeginScan

WdfChildListEndIteration

WdfChildListRequestChildEject

WdfChildListRetrieveNextDevice