Función WdfChildListRetrieveNextDevice (wdfchildlist.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfChildListRetrieveNextDevice recorre una lista secundaria especificada y recupera el siguiente dispositivo secundario que coincide con los criterios especificados.

Sintaxis

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

Parámetros

[in] ChildList

Identificador de un objeto de lista secundaria de marco.

[in] Iterator

Puntero a la misma estructura de WDF_CHILD_LIST_ITERATOR asignada por el autor de la llamada que el controlador proporcionó anteriormente a WdfChildListBeginIteration.

[out] Device

Puntero a una ubicación que recibe un identificador de un objeto de dispositivo de marco. El valor recibido es NULL si el parámetro Iterator especifica la marca WdfRetrievePendingChildren .

[in, out] Info

Puntero a una estructura de WDF_CHILD_RETRIEVE_INFO asignada por el autor de la llamada. Este puntero es opcional y puede ser NULL.

Valor devuelto

WdfChildListRetrieveNextDevice devuelve STATUS_SUCCESS u otro valor de estado para el que NT_SUCCESS(status) es igual a TRUE, si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Un parámetro de entrada no era válido.
STATUS_INFO_LENGTH_MISMATCH	El tamaño de la estructura WDF_CHILD_LIST_ITERATOR especificada por Iterator era incorrecto.
STATUS_INVALID_DEVICE_REQUEST	Se especificó una descripción de dirección, pero la lista secundaria no contenía descripciones de direcciones.
STATUS_NO_MORE_ENTRIES	El marco alcanzó el final de la lista secundaria.
STATUS_INVALID_DEVICE_STATE	El controlador no ha llamado a WdfChildListBeginIteration.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores del sistema si el controlador proporciona un identificador de objeto no válido.

Comentarios

Antes de llamar a WdfChildListRetrieveNextDevice, el controlador debe llamar a WdfChildListBeginIteration. Una vez que el controlador haya terminado de recorrer la lista secundaria, debe llamar a WdfChildListEndIteration. A continuación, el marco informa al administrador de Plug and Play (PnP) de los cambios realizados en la lista secundaria.

Cada vez que el controlador llama a WdfChildListRetrieveNextDevice, el método recupera el siguiente elemento secundario que coincide con los siguientes criterios de búsqueda:

El tipo del elemento secundario debe corresponder a marcas con tipo WDF_RETRIEVE_CHILD_FLAGS en la estructura WDF_CHILD_LIST_ITERATOR del controlador.
Si el controlador proporciona un puntero a una función de devolución de llamada EvtChildListIdentificationDescriptionCompare en su estructura WDF_CHILD_RETRIEVE_INFO , la función de devolución de llamada debe devolver TRUE.

Si el controlador proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionCompare , también debe proporcionar una descripción de identificación en la estructura WDF_CHILD_RETRIEVE_INFO. El marco usa la función de devolución de llamada para comparar el descriptor de identificación pasado con la descripción de un elemento secundario en la lista secundaria, si las marcas con tipo WDF_RETRIEVE_CHILD_FLAGS indican que el elemento secundario es un candidato coincidente. Si la función de devolución de llamada devuelve TRUE, la coincidencia se realiza correctamente. Si la función de devolución de llamada devuelve FALSE, el marco busca otro candidato.

Cuando WdfChildListRetrieveNextDevice encuentra una coincidencia, copia la descripción de identificación y la descripción de la dirección del elemento secundario en la estructura WDF_CHILD_RETRIEVE_INFO del controlador, si el puntero que especifica el parámetro Info no es NULL. (Tenga en cuenta que esta operación sobrescribe la descripción de identificación de entrada del controlador). El método también coloca un identificador en el objeto de dispositivo del elemento secundario en la ubicación que identifica el parámetro Device .

Para obtener más información sobre las listas secundarias, vea Enumeración dinámica.

Ejemplos

En el ejemplo de código siguiente se informa al marco de trabajo que se están expulsando todos los elementos secundarios de un dispositivo primario. En el ejemplo se obtiene la lista secundaria predeterminada de un dispositivo y se recorre la lista. Obtiene el descriptor de identificación de cada elemento secundario y pasa cada descriptor de identificación a 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;

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfchildlist.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)