EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE fonction de rappel (wdfchildlist.h)

Article
02/29/2024

[S’applique uniquement à KMDF]

La fonction de rappel de l’événement EvtChildListIdentificationDescriptionDuplicate d’un pilote duplique une description d’identification enfant.

Syntaxe

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

Paramètres

[in] ChildList

Handle d’un objet de liste enfant de framework.

[in] SourceIdentificationDescription

Pointeur vers une structure de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER qui identifie l’emplacement source de la description d’identification enfant.

[out] DestinationIdentificationDescription

Pointeur vers une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER qui identifie l’emplacement de destination de la description d’identification enfant en double.

Valeur retournée

La fonction de rappel EvtChildListIdentificationDescriptionDuplicate doit retourner STATUS_SUCCESS ou une autre valeur de status pour laquelle NT_SUCCESS(status) est égal à TRUE, si l’opération réussit. Sinon, cette fonction de rappel doit retourner une valeur status pour laquelle NT_SUCCESS(status) est FALSE.

Remarques

Si un pilote de bus utilise une énumération dynamique, il peut inscrire une fonction de rappel EvtChildListIdentificationDescriptionDuplicate en appelant WdfFdoInitSetDefaultChildListConfig ou WdfChildListCreate.

L’infrastructure dupliquez les descriptions d’identification fournies par le pilote afin qu’elle puisse avoir des copies internes des descriptions.

La fonction de rappel EvtChildListIdentificationDescriptionDuplicate doit créer une copie dupliquée d’une description d’identification. Un pilote doit fournir cette fonction de rappel si l’infrastructure ne peut pas appeler RtlCopyMemory pour dupliquer la description d’identification. (L’infrastructure ne peut pas appeler RtlCopyMemory si la description contient des pointeurs vers de la mémoire supplémentaire.)

Si votre pilote ne fournit pas de fonction de rappel EvtChildListIdentificationDescriptionDuplicate , l’infrastructure duplique les descriptions d’identification en appelant RtlCopyMemory.

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

Le pilote détermine qu’un appareil enfant existe.
Le pilote crée une description d’identification en remplissant une structure définie par le pilote qui contient une structure WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER et éventuellement en allouant dynamiquement de la mémoire supplémentaire pour stocker les informations d’identification qui ont une taille spécifique à l’appareil.
Le pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent pour signaler un appareil enfant, en fournissant un pointeur vers la description d’identification.
L’infrastructure appelle la fonction de rappel EvtChildListIdentificationDescriptionDuplicate (si elle existe) ou RtlCopyMemory pour dupliquer la description d’identification afin d’avoir une copie interne de la description.

L’infrastructure peut utiliser RtlCopyMemory pour dupliquer une description d’identification, si la 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 doit fournir une fonction de rappel EvtChildListIdentificationDescriptionDuplicate . La fonction de rappel doit effectuer les opérations suivantes :

Allouez de la mémoire supplémentaire, généralement en appelant ExAllocatePool.
Stockez l’adresse de la mémoire allouée dans la structure de description de l’adresse définie par le pilote (c’est-à-dire la structure DestinationIdentificationDescription de la fonction de rappel).
Copiez d’autres membres de structure de la structure SourceIdentificationDescription de la fonction de rappel vers la structure DestinationIdentificationDescription de la fonction de rappel.

La seule méthode d’objet de liste enfant du framework que la fonction de rappel EvtChildListIdentificationDescriptionDuplicate 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 EvtChildListIdentificationDescriptionDuplicate . Cette fonction de rappel doit uniquement effectuer des opérations liées à l’opération uplication, 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.

Si votre pilote fournit une fonction de rappel EvtChildListIdentificationDescriptionDuplicate , il peut également avoir besoin des fonctions de rappel EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare et EvtChildListIdentificationDescriptionCleanup .

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