WdfChildListRetrievePdo, fonction (wdfchildlist.h)

  • Article

[S’applique uniquement à KMDF]

La méthode WdfChildListRetrievePdo retourne un handle à l’objet d’appareil framework associé à une description enfant spécifiée dans une liste enfant.

Syntaxe

WDFDEVICE WdfChildListRetrievePdo(
  [in]      WDFCHILDLIST             ChildList,
  [in, out] PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
);

Paramètres

[in] ChildList

Handle d’un objet de liste enfant.

[in, out] RetrieveInfo

Pointeur vers une structure de WDF_CHILD_RETRIEVE_INFO allouée par le pilote que le pilote initialise avec la description d’identification de l’enfant à récupérer.

Valeur retournée

WdfChildListRetrievePdo retourne un handle à l’objet d’appareil framework si l’appareil enfant spécifié se trouve dans la liste enfant, s’il existe un objet d’appareil framework pour l’appareil enfant et si le framework a signalé l’existence de l’appareil au gestionnaire PnP. Sinon, la méthode retourne NULL. L’infrastructure retourne des informations status supplémentaires dans le membre Status de la structure WDF_CHILD_RETRIEVE_INFO.

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

Remarques

Avant d’appeler WdfChildListRetrievePdo, le pilote doit placer une description d’identification dans une structure WDF_CHILD_RETRIEVE_INFO .

La méthode WdfChildListRetrievePdo traverse la liste enfant spécifiée et recherche un enfant avec une description d’identification qui correspond à celle fournie par le pilote dans la structure WDF_CHILD_RETRIEVE_INFO. Si l’infrastructure trouve une correspondance et si l’enfant a une description d’adresse, l’infrastructure remplit la description de l’adresse de la structure.

Veillez à encapsuler cet appel avec WdfChildListBeginIteration et WdfChildListEndIteration pour protéger l’appelant contre la suppression soudaine de PnP de l’AOP sur un autre thread.

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

Exemples

L’exemple de code suivant recherche une liste enfant pour trouver un appareil enfant dont la description d’identification contient un numéro de série spécifié et obtient un handle pour l’objet d’appareil qui représente l’appareil enfant.

WDF_CHILD_LIST_ITERATOR iterator;
PDO_IDENTIFICATION_DESCRIPTION description;
WDF_CHILD_RETRIEVE_INFO info;
WDFDEVICE hChild;

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );

description.SerialNo = DeviceSerialNumber;

WDF_CHILD_RETRIEVE_INFO_INIT(
                             &info,
                             &description.Header
                             );

WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);
WdfChildListBeginIteration(childList, &iterator);

hChild = WdfChildListRetrievePdo(
                                 childList,
                                 &info
                                 );

... access hChild ...

WdfChildListEndIteration(childList, &iterator);

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)

Voir aussi

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_CHILD_RETRIEVE_INFO_INIT