EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE fonction de rappel (wdfchildlist.h)

Article
02/07/2025

[S’applique uniquement à KMDF]

La fonction de rappel d’événement EvtChildListAddressDescriptionDuplicate doublons une description d’adresse enfant.

Syntaxe

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [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 de 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

La fonction de rappel EvtChildListAddressDescriptionDuplicate doit retourner STATUS_SUCCESS, ou une autre valeur d’état pour laquelle NT_SUCCESS(status) est égal à TRUE, si l’opération réussit. Dans le cas contraire, cette fonction doit retourner une valeur d’état pour laquelle NT_SUCCESS(status) est égal à FALSE.

Remarques

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

Le framework doublons les descriptions d’adresses fournies par le pilote afin qu’elle puisse avoir des copies internes des descriptions.

La fonction de rappel EvtChildListAddressDescriptionDuplicate doit créer une copie en double d’une description d’adresse. 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 dupliquer la description de l’adresse. (L’infrastructure ne peut pas appeler RtlCopyMemory si la description contient des pointeurs vers une mémoire supplémentaire.)

Si votre pilote fournit des descriptions d’adresses, mais ne fournit pas de EvtChildListAddressDescriptionDuplicate fonction de rappel, l’infrastructure duplique les descriptions d’adresses 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’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 à l’appareil.
Le pilote appelle WdfChildListAddOrUpdateChildDescriptionAsPresent pour signaler un appareil enfant, en fournissant un pointeur vers la description de l’adresse.
L’infrastructure appelle la fonction de rappel EvtChildListAddressDescriptionDuplicate (le cas échéant) ou RtlCopyMemory pour dupliquer la description de l’adresse afin qu’elle puisse avoir une copie interne de la description.

L’infrastructure peut utiliser RtlCopyMemory pour dupliquer une description d’adresse, si la description se compose d’une structure unique avec une taille prédéterminée spécifiée par l'AddressDescriptionSize membre de la structure WDF_CHILD_ADDRESS_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 EvtChildListAddressDescriptionDuplicate fonction de rappel. 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 (autrement dit, la fonction de rappel DestinationAddressDescription structure).
Copiez d’autres membres de la structure de la fonction de rappel SourceAddressDescription structure vers la structure DestinationAddressDescription de la fonction de rappel.

La seule méthode d’objet de liste enfant framework que la fonction de rappel EvtChildListAddressDescriptionDuplicate peut appeler est WdfChildListGetDevice.

L’infrastructure acquiert un verrou d’objet de liste enfant interne avant d’appeler la fonction de rappel EvtChildListAddressDescriptionDuplicate. La fonction de rappel doit effectuer uniquement des opérations liées à l’opération de duplication décrite, comme 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.

Si votre pilote fournit une fonction de rappel EvtChildListAddressDescriptionDuplicate, il peut également être nécessaire EvtChildListAddressDescriptionCopy et EvtChildListAddressDescriptionCleanup fonctions de rappel.

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