WdfChildListRetrieveNextDevice, fonction (wdfchildlist.h)

Article
02/26/2024

[S’applique uniquement à KMDF]

La méthode WdfChildListRetrieveNextDevice traverse une liste enfant spécifiée et récupère l’appareil enfant suivant qui correspond aux critères spécifiés.

Syntaxe

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

Paramètres

[in] ChildList

Handle d’un objet de liste enfant de framework.

[in] Iterator

Pointeur vers la même structure de WDF_CHILD_LIST_ITERATOR allouée à l’appelant que celle fournie auparavant par le pilote à WdfChildListBeginIteration.

[out] Device

Pointeur vers un emplacement qui reçoit un handle vers un objet d’appareil framework. La valeur reçue est NULL si le paramètre Iterator spécifie l’indicateur WdfRetrievePendingChildren .

[in, out] Info

Pointeur vers une structure de WDF_CHILD_RETRIEVE_INFO allouée par l’appelant . Ce pointeur est facultatif et peut avoir la valeur NULL.

Valeur retournée

WdfChildListRetrieveNextDevice retourne STATUS_SUCCESS, ou une autre valeur status pour laquelle NT_SUCCESS(status) est égal à TRUE, si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’était pas valide.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_CHILD_LIST_ITERATOR spécifiée par Iterator était incorrecte
STATUS_INVALID_DEVICE_REQUEST	Une description d’adresse a été spécifiée, mais la liste enfant ne contenait pas de descriptions d’adresses.
STATUS_NO_MORE_ENTRIES	L’infrastructure a atteint la fin de la liste enfant.
STATUS_INVALID_DEVICE_STATE	Le pilote n’a pas appelé WdfChildListBeginIteration.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue système case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Avant d’appeler WdfChildListRetrieveNextDevice, votre pilote doit appeler WdfChildListBeginIteration. Une fois que le pilote a terminé de parcourir la liste enfant, il doit appeler WdfChildListEndIteration. L’infrastructure informe ensuite le gestionnaire Plug-and-Play (PnP) des modifications apportées à la liste enfant.

Chaque fois que le pilote appelle WdfChildListRetrieveNextDevice, la méthode récupère l’enfant suivant qui correspond aux critères de recherche suivants :

Le type de l’enfant doit correspondre à WDF_RETRIEVE_CHILD_FLAGS indicateurs typés dans la structure de WDF_CHILD_LIST_ITERATOR du pilote.
Si le pilote fournit un pointeur vers une fonction de rappel EvtChildListIdentificationDescriptionCompare dans sa structure WDF_CHILD_RETRIEVE_INFO , la fonction de rappel doit retourner TRUE.

Si le pilote fournit une fonction de rappel EvtChildListIdentificationDescriptionCompare , il doit également fournir une description d’identification dans la structure WDF_CHILD_RETRIEVE_INFO. L’infrastructure utilise la fonction de rappel pour comparer le descripteur d’identification transmis à la description d’un enfant dans la liste enfant, si les indicateurs de type WDF_RETRIEVE_CHILD_FLAGS indiquent que l’enfant est un candidat de correspondance. Si la fonction de rappel retourne TRUE, la correspondance réussit. Si la fonction de rappel retourne FALSE, l’infrastructure recherche un autre candidat.

Lorsque WdfChildListRetrieveNextDevice trouve une correspondance, il copie la description d’identification et la description de l’adresse de l’enfant dans la structure WDF_CHILD_RETRIEVE_INFO du pilote, si le pointeur que le paramètre Info spécifie n’est pas NULL. (Notez que cette opération remplace la description d’identification d’entrée du pilote.) La méthode place également un handle dans l’objet d’appareil de l’enfant à l’emplacement que le paramètre Device identifie.

Pour plus d’informations sur les listes enfants, consultez Énumération dynamique.

Exemples

L’exemple de code suivant informe l’infrastructure que tous les enfants d’un appareil parent sont éjectés. L’exemple obtient la liste enfant par défaut d’un appareil et décrit la liste. Il obtient le descripteur d’identification de chaque enfant et passe chaque descripteur d’identification à 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;

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfchildlist.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)