Função WdfChildListRetrieveNextDevice (wdfchildlist.h)
[Aplica-se somente ao KMDF]
O método WdfChildListRetrieveNextDevice percorre 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 Iterador especificar o sinalizador de WdfRetrievePendingChildren.
[in, out] Info
Um ponteiro para uma estrutura de WDF_CHILD_RETRIEVE_INFO alocada pelo chamador. Esse ponteiro é opcional e pode ser NULL.
Valor de retorno
WdfChildListRetrieveNextDevice retorna STATUS_SUCCESS ou outro valor de status para o qual NT_SUCCESS(status) é igual a VERDADEIRO, 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 |
|---|---|
|
Um parâmetro de entrada era inválido. |
|
O tamanho da estrutura de WDF_CHILD_LIST_ITERATOR que iterador especificado estava incorreto |
|
Uma descrição de endereço foi especificada, mas a lista filho não continha descrições de endereço. |
|
A estrutura chegou ao final da lista filho. |
|
O driver não chamou WdfChildListBeginIteration. |
Esse método também pode retornar outros valores NTSTATUS .
Uma verificação de bugs do sistema ocorre se o driver fornece um identificador de objeto inválido.
Observações
Antes de chamar WdfChildListRetrieveNextDevice, o driver deve chamar WdfChildListBeginIteration. Depois que o driver terminar de percorrer a lista filho, ele deverá chamar WdfChildListEndIteration. Em seguida, a estrutura informa ao gerenciador do Plug and Play (PnP) sobre todas as 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 tipado em WDF_RETRIEVE_CHILD_FLAGSna estrutura de WDF_CHILD_LIST_ITERATOR do driver.
- Se o driver fornecer um ponteiro para um função de retorno de chamada EvtChildListIdentificationDescriptionCompare em sua estrutura de WDF_CHILD_RETRIEVE_INFO, a função de retorno de chamada deverá retornar TRUE.
Quando WdfChildListRetrieveNextDevice encontrar uma correspondência, ele copiará a descrição de identificação e a descrição do endereço da criança na estrutura de WDF_CHILD_RETRIEVE_INFO do driver, se o ponteiro que o parâmetro informações de especificar 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 do dispositivo 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 filho 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 |
|---|---|
| da Plataforma de Destino | Universal |
| versão mínima do KMDF | 1.0 |
| cabeçalho | wdfchildlist.h (inclua Wdf.h) |
| biblioteca | Wdf01000.sys (consulte o Controle de Versão da Biblioteca da Estrutura.) |
| IRQL | <= DISPATCH_LEVEL |
| regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Consulte também
EvtChildListIdentificationDescriptionCompare