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 d’un 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 d’un enfant.

[in] SecondIdentificationDescription

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

Valeur retournée

La fonction de rappel EvtChildListIdentificationDescriptionCompare doit retourner TRUE si les deux descriptions d’identification enfants correspondent. Dans le cas contraire, cette fonction doit retourner FALSE.

Remarques

Si un pilote de bus utilise une é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 à cas spécial 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 si elles 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 de la 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 d’adresse associée à la copie d’une description d’identification par l’infrastructure, 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, l’infrastructure appelle la fonction de rappel EvtChildListIdentificationDescriptionCompareCompare (si elle existe) 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 d’adresse en mémoire que le pilote a fournie quand 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 le membre IdentificationDescriptionSize de la structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER . Toutefois, parfois, la description doit également contenir des informations supplémentaires stockées dans la mémoire allouée dynamiquement. Dans ce cas, vous définissez généralement une structure de description afin qu’un membre pointe vers la mémoire allouée dynamiquement et que votre pilote fournisse une fonction de rappel EvtChildListIdentificationDescriptionCompare .

Cette fonction de rappel détermine si deux descriptions d’identification représentent le même appareil. La fonction de rappel n’a peut-être pas besoin de comparer tous les membres de la structure pour effectuer cette détermination. Par exemple, supposons qu’une description d’identification contienne 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 une fonction de rappel EvtChildListIdentificationDescriptionCompare supplémentaire que l’infrastructure utilise lors de la recherche de la description suivante à récupérer. L’infrastructure recherche les appareils enfants qui correspondent aux indicateurs de type WDF_RETRIEVE_CHILD_FLAGS fournis par le pilote. Si un pilote fournit une fonction de rappel EvtChildListIdentificationDescriptionCompare spéciale, 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’appelle pasRtlCompareMemory. Elle retourne simplement chaque appareil enfant qui correspond aux indicateurs spécifiés.

La seule méthode d’objet de liste enfant du framework que la fonction de rappel EvtChildListIdentificationDescriptionCompare d’un pilote 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 uniquement effectuer des opérations liées à l’opération de comparaison, telles que l’appel de méthodes d’objet mémoire framework et l’accès à l’espace de contexte de l’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.