AppendTailList, fonction (wdm.h)

Article
02/27/2024

La routine AppendTailList ajoute une liste doublement liée de structures LIST_ENTRY à la fin d’une autre liste doublement liée de structures LIST_ENTRY .

Syntaxe

void AppendTailList(
  [in, out] PLIST_ENTRY ListHead,
  [in, out] PLIST_ENTRY ListToAppend
);

Paramètres

[in, out] ListHead

Pointeur vers le début de la liste vers laquelle la liste pointée par ListToAppend doit être ajouté. Ce paramètre doit être un pointeur valide et non NULL vers la structure LIST_ENTRY qui est le chef d’une liste. Cette liste peut être vide.

[in, out] ListToAppend

Pointeur vers la première entrée de la liste à ajouter à la liste pointée par ListHead. Ce paramètre doit être un pointeur non NULL valide vers la structure LIST_ENTRY qui est la première entrée d’une liste sans tête. Pour plus d'informations, consultez la section Notes.

Valeur de retour

None

Remarques

Cette routine construit une liste qui contient toutes les entrées combinées des listes ListHead et ListToAppend d’entrée . Lorsque la routine retourne, la structure LIST_ENTRY pointée par le paramètre ListHead est le chef de la liste combinée résultante. La structure LIST_ENTRY pointée par le paramètre ListToAppend est une entrée dans la liste combinée résultante.

L’appelant définit le paramètre ListToAppend pour qu’il pointe vers la première entrée de la liste à ajouter. À cet égard, AppendTailList n’est pas conforme à la convention suivie par les autres routines de liste doublement liées qui utilisent la structure LIST_ENTRY . Dans ces autres routines, un paramètre qui représente une liste pointe vers la tête de liste plutôt que vers la première entrée de la liste. Si votre code de pilote utilise un en-tête de liste pour représenter la liste à ajouter, l’en-tête de liste doit être supprimé de cette liste avant que la liste ne soit transmise en tant que paramètre ListToAppend à AppendTailList. Pour obtenir un exemple de code qui montre comment supprimer cet en-tête de liste, consultez Exemples.

AppendTailList peut être utilisé pour insérer une seule entrée à la fin d’une liste, mais les membres Flink et Blink de la structure LIST_ENTRY pointées par ListToAppend doivent d’abord être initialisés, généralement en appelant la routine InitializeListHead . En revanche, la routine InsertTailList ne nécessite pas l’initialisation des membres Flink et Blink de la structure LIST_ENTRY pointée par le paramètre Entry avant l’appel InsertTailList . Pour cette raison, InsertTailList peut être plus pratique à utiliser pour insérer une seule entrée à la fin d’une liste.

Un pilote peut accéder aux membres Flink et Blink d’un LIST_ENTRY, mais les membres doivent uniquement être mis à jour par les routines système fournies à cet effet.

Pour plus d’informations sur l’utilisation de cette routine lors de l’implémentation d’une liste doublement liée, consultez Singly and Doubly Linked Listes.

Les appelants d’AppendTailList peuvent être en cours d’exécution à n’importe quel IRQL. Si AppendTailList est appelé dans IRQL >= DISPATCH_LEVEL, le stockage des entrées de liste doit être résident en mémoire.

Exemples

L’exemple de code suivant montre comment écrire une fonction nommée MyAppendTailList qui est similaire à AppendTailList, mais qui traite le paramètre ListToAppend comme un pointeur vers une tête de liste plutôt que comme pointeur vers la première entrée d’une liste (sans tête). Contrairement à AppendTailList, la MyAppendTailList fonction évite d’inclure la structure LIST_ENTRY pointée par le paramètre ListToAppend dans les entrées ajoutées à la liste pointée par le paramètre ListHead .

VOID MyAppendTailList(
    _Inout_  PLIST_ENTRY ListHead,
    _Inout_  PLIST_ENTRY ListToAppend
    )
{
    PLIST_ENTRY entry = ListToAppend->Flink;

    if (!IsListEmpty(ListToAppend))
    {
        RemoveEntryList(ListToAppend);
        InitializeListHead(ListToAppend);
        AppendTailList(ListHead, entry);
    }
}

La MyAppendTailList fonction de cet exemple de code traite les paramètres ListHead et ListToAppend comme des pointeurs vers les têtes de liste. Lorsque cette fonction retourne, la liste pointée par ListToAppend est vide ; autrement dit, il se compose d’un tête de liste qui n’a aucune entrée de liste associée. Toutes les entrées qui se trouvaient initialement dans cette liste ont été ajoutées à la liste pointée par ListHead.

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
IRQL	N’importe quel niveau (voir la section Remarques)

Voir aussi