EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE fonction de rappel (wdfchildlist.h)

Article
08/08/2023

[S’applique uniquement à KMDF]

La fonction de rappel d’événement evtChildListIdentificationDescriptionCompare du pilote compare une description d’identification enfant à une autre.

Syntaxe

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

Paramètres

[in] ChildList

Handle d’un objet de liste enfant de framework.

[in] FirstIdentificationDescription

Pointeur vers une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER qui identifie la description d’identification enfant.

[in] SecondIdentificationDescription

Pointeur vers une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER qui identifie une autre description d’identification enfant.

Valeur de retour

La fonction de rappel EvtChildListIdentificationDescriptionCompare doit retourner TRUE si les deux descriptions d’identification enfant correspondent. Sinon, cette fonction doit retourner faux.

Remarques

Si un pilote de bus utilise énumération dynamique, il peut inscrire une fonction de rappel EvtChildListIdentificationDescriptionCompare en appelant WdfFdoInitSetDefaultChildListConfig ou WdfChildListCreate. Le pilote peut également inscrire une deuxième fonction de rappel evtChildListIdentificationDescriptionCompare lorsqu’il appelle WdfChildListRetrieveNextDevice.

L’infrastructure compare deux descriptions d’identification lorsqu’elle doit déterminer si les deux descriptions identifient le même appareil.

La fonction de rappel EvtChildListIdentificationDescriptionCompare doit comparer le contenu de deux descriptions d’identification et retourner TRUE s’ils correspondent. Un pilote doit fournir cette fonction de rappel si l’infrastructure ne peut pas appeler RtlCompareMemory pour comparer les descriptions d’identification. (L’infrastructure ne peut pas appeler RtlCompareMemory si les descriptions contiennent des pointeurs vers une mémoire supplémentaire.)

Si votre pilote ne fournit pas de fonction de rappel EvtChildListIdentificationDescriptionCompare, l’infrastructure compare les descriptions d’identification en appelant RtlCompareMemory.

Les étapes suivantes décrivent un scénario possible :

Le pilote appelle WdfChildListRetrieveAddressDescription pour obtenir la description de l’adresse associée à la copie de l’infrastructure d’une description d’identification, qui est stockée dans une liste enfant.
L’infrastructure traverse la liste enfant. Pour déterminer si la description d’identification d’un enfant correspond à celle spécifiée par le pilote lorsqu’il a appelé WdfChildListRetrieveAddressDescription, le framework appelle la fonction de rappel EvtChildListIdentificationDescriptionCompare (le cas échéant) ou RtlCompareMemory.
Si les deux descriptions d’identification correspondent (et que la comparaison retourne TRUE), l’infrastructure cesse de parcourir la liste.
L’infrastructure copie la description de l’adresse en mémoire que le pilote a fourni lorsqu’il a appelé WdfChildListRetrieveAddressDescription.

L’infrastructure peut utiliser RtlCompareMemory pour comparer les descriptions d’identification, si chaque description se compose d’une structure unique avec une taille prédéterminée spécifiée par l'IdentificationDescriptionSize membre de la structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER. Toutefois, parfois, la description doit également contenir des informations supplémentaires stockées dans une mémoire allouée dynamiquement. Dans ce cas, vous allez généralement définir une structure de description afin qu’un membre pointe vers la mémoire allouée dynamiquement, et votre pilote doit fournir un EvtChildListIdentificationDescriptionCompare fonction de rappel.

Cette fonction de rappel détermine si deux descriptions d’identification représentent le même appareil. La fonction de rappel peut ne pas avoir à comparer tous les membres de la structure pour effectuer cette détermination. Par exemple, supposons qu’une description d’identification contient un numéro de série et un ensemble d’identificateurs matériels, comme suit :

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

Dans ce cas, la fonction de rappel EvtChildListIdentificationDescriptionCompare doit probablement comparer uniquement les membres DeviceSerialNumber pour déterminer si deux descriptions représentent le même appareil.

Si votre pilote appelle WdfChildListRetrieveNextDevice pour parcourir une liste d’appareils, vous pouvez fournir un supplémentaire EvtChildListIdentificationDescriptionCompare fonction de rappel utilisée par l’infrastructure lors de la recherche de la description suivante à récupérer. L’infrastructure recherche des appareils enfants qui correspondent aux indicateurs WDF_RETRIEVE_CHILD_FLAGS-typés fournis par le pilote. Si un pilote fournit un evtChildListIdentificationDescriptionCompare fonction de rappel, l’infrastructure utilise la fonction de rappel pour affiner la recherche. Si le pilote ne fournit pas de fonction de rappel EvtChildListIdentificationDescriptionCompare, l’infrastructure n'pas appeler RtlCompareMemory--il retourne simplement chaque appareil enfant qui correspond aux indicateurs spécifiés.

La seule méthode d’objet de liste enfant framework qu’une fonction de rappel EvtChildListIdentificationDescriptionCompare peut appeler est WdfChildListGetDevice.

L’infrastructure acquiert un verrou d’objet de liste enfant interne avant d’appeler la fonction de rappel EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare. La fonction de rappel doit effectuer uniquement des opérations liées à l’opération de comparaison, telles que l’appel des méthodes d’objet mémoire du framework et l’accès à l’espace de contexte d’objet. Il ne doit pas appeler des méthodes qui accèdent à d’autres pilotes.

Pour plus d’informations sur l’énumération dynamique, consultez énumération des appareils sur un bus.