WdfChildListRetrieveNextDevice function

Description

[Applies to KMDF only]

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

Parameters

ChildList [in]

A handle to a framework child-list object.

Iterator [in]

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

Device [out]

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.

Info [in, out]

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:

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;

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