WdfChildListRetrieveNextDevice method

[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

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:

Return codeDescription
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

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_LIST_ITERATOR
WDF_CHILD_LIST_ITERATOR_INIT
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT
WDF_CHILD_RETRIEVE_INFO
WDF_RETRIEVE_CHILD_FLAGS
EvtChildListIdentificationDescriptionCompare
WdfChildListBeginScan
WdfChildListRequestChildEject
WdfChildListRetrieveNextDevice
WdfChildListBeginIteration
WdfChildListEndIteration

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft