Compartir a través de


Función WdfChildListRetrieveNextDevice (wdfchildlist.h)

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

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)

Consulte también

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