EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY fonction de rappel (wdfchildlist.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La fonction de rappel d’événement EvtChildListAddressDescriptionCopy d’un pilote copie une description d’adresse enfant d’un emplacement spécifié vers un autre.

Syntaxe

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

Paramètres

[in] ChildList

Handle d’un objet de liste enfant du framework.

[in] SourceAddressDescription

Pointeur vers une structure WDF_CHILD_ADDRESS_DESCRIPTION_HEADER qui identifie l’emplacement source de la description de l’adresse enfant.

[out] DestinationAddressDescription

Pointeur vers une structure WDF_CHILD_ADDRESS_DESCRIPTION_HEADER qui identifie l’emplacement de destination de la description de l’adresse enfant.

Valeur de retour

None

Remarques

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

L’infrastructure copie les informations d’une description d’adresse fournie par le pilote vers une autre lorsqu’elle doit mettre à jour une description existante avec de nouvelles informations, ou quand elle doit transmettre le contenu d’une description d’adresse au pilote.

La fonction de rappel EvtChildListAddressDescriptionCopy doit copier le contenu d’une description source dans une description de destination. Un pilote doit fournir cette fonction de rappel si ses appareils enfants nécessitent une description d’adresse et si l’infrastructure ne peut pas appeler RtlCopyMemory pour copier la description de l’adresse. (L’infrastructure ne peut pas appeler RtlCopyMemory si la description contient des pointeurs vers de la mémoire supplémentaire.)

Si votre pilote fournit des descriptions d’adresses, mais qu’il ne fournit pas de fonction de rappel EvtChildListAddressDescriptionCopy , l’infrastructure copie les descriptions d’adresses en appelant RtlCopyMemory.

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

Le pilote détermine qu’il existe un périphérique enfant.
Le pilote crée une description d’adresse en remplissant une structure définie par le pilote qui contient une structure WDF_CHILD_ADDRESS_DESCRIPTION_HEADER et éventuellement en allouant dynamiquement de la mémoire supplémentaire pour stocker les informations d’adresse qui ont une taille spécifique au périphérique.
Le pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent pour signaler un appareil enfant, en fournissant un pointeur vers la description de l’adresse.
L’infrastructure détermine que le pilote a précédemment signalé l’appareil, de sorte que l’infrastructure peut mettre à jour l’ancienne description de l’adresse de l’appareil avec de nouvelles informations.
L’infrastructure appelle la fonction de rappel EvtChildListAddressDescriptionCopy (si elle existe) ou RtlCopyMemory pour copier les nouvelles informations de description d’adresse dans la description d’adresse existante.

L’infrastructure peut utiliser RtlCopyMemory pour copier une description d’adresse, si la description se compose d’une structure unique avec une taille prédéterminée spécifiée par le membre AddressDescriptionSize de la structure WDF_CHILD_ADDRESS_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 votre pilote doit fournir une fonction de rappel EvtChildListAddressDescriptionCopy . La fonction de rappel doit effectuer les opérations suivantes :

Dans les structures SourceAddressDescription et DestinationAddressDescription de la fonction de rappel, recherchez les pointeurs vers la mémoire allouée dynamiquement.
Copiez la mémoire allouée dynamiquement de la source vers la destination, à l’aide des pointeurs.
Copiez les autres membres de structure de la structure SourceAddressDescription de la fonction de rappel vers la structure DestinationAddressDescription de la fonction de rappel.

La seule méthode d’objet de liste enfant du framework que la fonction de rappel EvtChildListAddressDescriptionCopy 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 EvtChildListAddressDescriptionCopy . La fonction de rappel doit uniquement effectuer des opérations liées à l’opération de copie décrite, telles que l’appel de méthodes d’objet de mémoire d’infrastructure et l’accès à l’espace contextuel 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 EvtChildListAddressDescriptionCopy , il peut également avoir besoin des fonctions de rappel EvtChildListAddressDescriptionDuplicate et EvtChildListAddressDescriptionCleanup .

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