EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY fonction de rappel (wdfchildlist.h)

  • Article

[S’applique uniquement à KMDF]

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

Syntaxe

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY EvtWdfChildListIdentificationDescriptionCopy;

void EvtWdfChildListIdentificationDescriptionCopy(
  [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.

Valeur de retour

None

Remarques

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

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

La fonction de rappel EvtChildListIdentificationDescriptionCopy doit copier le contenu d’une description source dans une description de destination. Un pilote doit fournir cette fonction de rappel si l’infrastructure ne peut pas appeler RtlCopyMemory pour copier 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 EvtChildListIdentificationDescriptionCopy , l’infrastructure copie les descriptions d’identification en appelant RtlCopyMemory.

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

  1. Le pilote qui traverse une liste enfant appelle WdfChildListRetrieveNextDevice. Le pilote fournit une structure WDF_CHILD_RETRIEVE_INFO afin qu’il puisse recevoir la description d’identification de l’appareil enfant.
  2. L’infrastructure appelle la fonction de rappel EvtChildListIdentificationDescriptionCopy (si elle existe) ou RtlCopyMemory pour copier la description d’identification de l’appareil. La source de l’opération de copie est la copie interne de l’infrastructure de la description. La destination est la mémoire que le pilote a allouée et identifiée dans sa structure WDF_CHILD_RETRIEVE_INFO.
L’infrastructure peut utiliser RtlCopyMemory pour copier 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 EvtChildListIdentificationDescriptionCopy . La fonction de rappel doit effectuer les opérations suivantes :
  1. Dans les structures SourceIdentificationDescription et DestinationIdentificationDescription de la fonction de rappel, recherchez les pointeurs vers la mémoire allouée dynamiquement.
  2. Copiez la mémoire allouée dynamiquement de la source vers la destination, à l’aide des pointeurs.
  3. 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 EvtChildListIdentificationDescriptionCopy 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 EvtChildListIdentificationDescriptionCopy . La fonction de rappel doit uniquement effectuer des opérations liées à l’opération de copie, telles que l’appel de méthodes d’objet mémoire d’infrastructure 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 EvtChildListIdentificationDescriptionCopy , il peut également avoir besoin de fonctions de rappel EvtChildListIdentificationDescriptionDuplicate, EvtChildListIdentificationDescriptionCompare et EvtChildListIdentificationDescriptionCleanup .

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

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.0
En-tête wdfchildlist.h (inclure Wdf.h)
IRQL <= DISPATCH_LEVEL

Voir aussi

EvtChildListIdentificationDescriptionCleanup

EvtChildListIdentificationDescriptionCompare

EvtChildListIdentificationDescriptionDuplicate

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WdfChildListCreate

WdfChildListGetDevice

WdfFdoInitSetDefaultChildListConfig