Funzione WdfChildListRetrieveNextDevice (wdfchildlist.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

Il metodo WdfChildListRetrieveNextDevice attraversa un elenco figlio specificato e recupera il dispositivo figlio successivo che corrisponde ai criteri specificati.

Sintassi

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

Parametri

[in] ChildList

Handle per un oggetto elenco figlio del framework.

[in] Iterator

Puntatore alla stessa struttura WDF_CHILD_LIST_ITERATOR allocata dal chiamante fornita in precedenza dal driver a WdfChildListBeginIteration.

[out] Device

Puntatore a una posizione che riceve un handle per un oggetto dispositivo framework. Il valore ricevuto è NULL se il parametro Iterator specifica il flag WdfRetrievePendingChildren .

[in, out] Info

Puntatore a una struttura WDF_CHILD_RETRIEVE_INFO allocata dal chiamante. Questo puntatore è facoltativo e può essere NULL.

Valore restituito

WdfChildListRetrieveNextDevice restituisce STATUS_SUCCESS o un altro valore di stato per cui NT_SUCCESS(status) è TRUE, se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Parametro di input non valido.
STATUS_INFO_LENGTH_MISMATCH	Dimensioni della struttura WDF_CHILD_LIST_ITERATOR specificata dall'iteratore non corretto
STATUS_INVALID_DEVICE_REQUEST	È stata specificata una descrizione dell'indirizzo, ma l'elenco figlio non contiene descrizioni degli indirizzi.
STATUS_NO_MORE_ENTRIES	Il framework ha raggiunto la fine dell'elenco figlio.
STATUS_INVALID_DEVICE_STATE	Il driver non ha chiamato WdfChildListBeginIteration.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Un controllo dei bug di sistema si verifica se il driver fornisce un handle di oggetto non valido.

Commenti

Prima di chiamare WdfChildListRetrieveNextDevice, il driver deve chiamare WdfChildListBeginIteration. Al termine dell'attraversamento dell'elenco figlio, il driver deve chiamare WdfChildListEndIteration. Il framework informa quindi il responsabile Plug and Play (PnP) di tutte le modifiche apportate all'elenco figlio.

Ogni volta che il driver chiama WdfChildListRetrieveNextDevice, il metodo recupera il figlio successivo che corrisponde ai criteri di ricerca seguenti:

Il tipo dell'elemento figlio deve corrispondere ai flag tipizzato WDF_RETRIEVE_CHILD_FLAGS nella struttura di WDF_CHILD_LIST_ITERATOR del driver.
Se il driver fornisce un puntatore a una funzione di callback EvtChildListIdentificationDescriptionCompare nella relativa struttura di WDF_CHILD_RETRIEVE_INFO , la funzione di callback deve restituire TRUE.

Se il driver fornisce una funzione di callback EvtChildListIdentificationDescriptionCompare , deve anche fornire una descrizione di identificazione nella struttura WDF_CHILD_RETRIEVE_INFO. Il framework usa la funzione di callback per confrontare il descrittore di identificazione passato con la descrizione di un figlio nell'elenco figlio, se i flag tipizzato WDF_RETRIEVE_CHILD_FLAGS indicano che l'elemento figlio è un candidato corrispondente. Se la funzione di callback restituisce TRUE, la corrispondenza ha esito positivo. Se la funzione di callback restituisce FALSE, il framework cerca un altro candidato.

Quando WdfChildListRetrieveNextDevice trova una corrispondenza, copia la descrizione di identificazione e la descrizione dell'indirizzo dell'elemento figlio nella struttura WDF_CHILD_RETRIEVE_INFO del driver, se il puntatore specificato dal parametro Info non è NULL. Si noti che questa operazione sovrascrive la descrizione dell'identificazione di input del driver. Il metodo inserisce anche un handle per l'oggetto dispositivo dell'elemento figlio nella posizione identificata dal parametro Device .

Per altre informazioni sugli elenchi figlio, vedere Enumerazione dinamica.

Esempio

L'esempio di codice seguente informa il framework che tutti gli elementi figlio di un dispositivo padre vengono espulsi. Nell'esempio viene ottenuto l'elenco figlio predefinito di un dispositivo e viene illustrato l'elenco. Ottiene il descrittore di identificazione di ogni figlio e passa ogni descrittore di identificazione 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;

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfchildlist.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)