Função WdfChildListRetrieveNextDevice (wdfchildlist.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfChildListRetrieveNextDevice atravessa uma lista filho especificada e recupera o próximo dispositivo filho que corresponde aos critérios especificados.

Sintaxe

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

Um identificador para um objeto de lista filho da estrutura.

[in] Iterator

Um ponteiro para a mesma estrutura de WDF_CHILD_LIST_ITERATOR alocada pelo chamador que o driver forneceu anteriormente para WdfChildListBeginIteration.

[out] Device

Um ponteiro para um local que recebe um identificador para um objeto de dispositivo de estrutura. O valor recebido será NULL se o parâmetro Iterator especificar o sinalizador WdfRetrievePendingChildren .

[in, out] Info

Um ponteiro para uma estrutura de WDF_CHILD_RETRIEVE_INFO alocada pelo chamador. Esse ponteiro é opcional e pode ser NULL.

Retornar valor

WdfChildListRetrieveNextDevice retorna STATUS_SUCCESS ou outro valor status para o qual NT_SUCCESS(status) é igual a TRUE, se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro de entrada era inválido.
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura de WDF_CHILD_LIST_ITERATOR especificada pelo Iterador estava incorreto
STATUS_INVALID_DEVICE_REQUEST	Uma descrição do endereço foi especificada, mas a lista filho não continha descrições de endereço.
STATUS_NO_MORE_ENTRIES	A estrutura chegou ao final da lista filho.
STATUS_INVALID_DEVICE_STATE	O driver não chamou WdfChildListBeginIteration.

Esse método também pode retornar outros valores NTSTATUS.

Um bug do sistema marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Antes de chamar WdfChildListRetrieveNextDevice, seu driver deve chamar WdfChildListBeginIteration. Depois que o driver terminar de percorrer a lista filho, ele deverá chamar WdfChildListEndIteration. Em seguida, a estrutura informa o gerente de Plug and Play (PnP) de quaisquer alterações feitas na lista filho.

Sempre que o driver chama WdfChildListRetrieveNextDevice, o método recupera o próximo filho que corresponde aos seguintes critérios de pesquisa:

O tipo da criança deve corresponder a sinalizadores do tipo WDF_RETRIEVE_CHILD_FLAGS na estrutura de WDF_CHILD_LIST_ITERATOR do driver.
Se o driver fornecer um ponteiro para uma função de retorno de chamada EvtChildListIdentificationDescriptionCompare em sua estrutura WDF_CHILD_RETRIEVE_INFO , a função de retorno de chamada deverá retornar TRUE.

Se o driver fornecer uma função de retorno de chamada EvtChildListIdentificationDescriptionCompare , ele também deverá fornecer uma descrição de identificação na estrutura WDF_CHILD_RETRIEVE_INFO. A estrutura usa a função de retorno de chamada para comparar o descritor de identificação passado com a descrição de uma criança na lista filho, se os sinalizadores do tipo WDF_RETRIEVE_CHILD_FLAGS indicarem que o filho é um candidato à correspondência. Se a função de retorno de chamada retornar TRUE, a correspondência será bem-sucedida. Se a função de retorno de chamada retornar FALSE, a estrutura procurará outro candidato.

Quando WdfChildListRetrieveNextDevice encontra uma correspondência, ele copia a descrição de identificação do filho e a descrição do endereço na estrutura de WDF_CHILD_RETRIEVE_INFO do driver, se o ponteiro especificado pelo parâmetro Info não for NULL. (Observe que essa operação substitui a descrição de identificação de entrada do driver.) O método também coloca um identificador no objeto de dispositivo do filho no local identificado pelo parâmetro Device .

Para obter mais informações sobre listas filho, consulte Enumeração dinâmica.

Exemplos

O exemplo de código a seguir informa à estrutura que todos os filhos de um dispositivo pai estão sendo ejetados. O exemplo obtém a lista filho padrão de um dispositivo e percorre a lista. Ele obtém o descritor de identificação de cada criança e passa cada descritor de identificação para 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	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfchildlist.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<= DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)