AppendTailList-Funktion (wdm.h)

Die AppendTailList-Routine fügt eine doppelt verknüpfte Liste von LIST_ENTRY Strukturen an das Ende einer anderen doppelt verknüpften Liste von LIST_ENTRY-Strukturen an.

Syntax

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

Parameter

[in, out] ListHead

Ein Zeiger auf den Kopf der Liste, auf den die Liste von ListToAppend verweist, soll angefügt werden. Dieser Parameter muss ein gültiger Zeiger ohne NULL auf die LIST_ENTRY-Struktur sein, die der Kopf einer Liste ist. Diese Liste kann leer sein.

[in, out] ListToAppend

Ein Zeiger auf den ersten Eintrag in der Liste, der an die Liste angefügt werden soll, auf die von ListHead verwiesen wird. Dieser Parameter muss ein gültiger Nicht-NULL-Zeiger auf die LIST_ENTRY-Struktur sein, die der erste Eintrag in einer kopflosen Liste ist. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Keine

Bemerkungen

Diese Routine erstellt eine Liste, die alle kombinierten Einträge aus den Eingabelisten ListHead und ListToAppend enthält. Wenn die Routine zurückgegeben wird, ist die LIST_ENTRY Struktur, auf die der ListHead-Parameter verweist, der Kopf der resultierenden kombinierten Liste. Die LIST_ENTRY Struktur, auf die der Parameter ListToAppend verweist, ist ein Eintrag in der resultierenden kombinierten Liste.

Der Aufrufer legt den ListToAppend-Parameter so fest, dass er auf den ersten Eintrag in der Liste verweist, der angefügt werden soll. In dieser Hinsicht entspricht AppendTailList nicht der Konvention, gefolgt von den anderen doppelt verknüpften Listenroutinen, die die LIST_ENTRY-Struktur verwenden. In diesen anderen Routinen verweist ein Parameter, der eine Liste darstellt, auf den Listenkopf und nicht auf den ersten Eintrag in der Liste. Wenn der Treibercode einen Listenkopf verwendet, um die anzufügende Liste darzustellen, muss der Listenkopf aus dieser Liste entfernt werden, bevor die Liste als ListToAppend-Parameter an AppendTailList übergeben wird. Ein Codebeispiel, das zeigt, wie Sie diesen Listenkopf entfernen, finden Sie unter Beispiele.

AppendTailList kann verwendet werden, um einen einzelnen Eintrag am Ende einer Liste einzufügen, aber die Elemente Flink und Blink der LIST_ENTRY Struktur, auf die von ListToAppend verwiesen wird, müssen zuerst initialisiert werden, in der Regel durch Aufrufen der InitializeListHead-Routine . Im Gegensatz dazu erfordert die InsertTailList-Routine nicht, dass die Elemente Flink und Blink der LIST_ENTRY Struktur, auf die der Entry-Parameter verweist, vor dem InsertTailList-Aufruf initialisiert werden. Aus diesem Grund ist InsertTailList möglicherweise bequemer, um einen einzelnen Eintrag am Ende einer Liste einzufügen.

Ein Treiber kann auf die Flink - und Blink-Member eines LIST_ENTRY zugreifen, aber die Member müssen nur von den zu diesem Zweck bereitgestellten Systemroutinen aktualisiert werden.

Informationen zur Verwendung dieser Routine beim Implementieren einer doppelt verknüpften Liste finden Sie unter Singly und Doubly Linked Listen.

Aufrufer von AppendTailList können in jedem IRQL ausgeführt werden. Wenn AppendTailList unter IRQL >= DISPATCH_LEVEL aufgerufen wird, muss der Speicher für die Listeneinträge speicherresident sein.

Beispiele

Das folgende Codebeispiel zeigt, wie eine Funktion namens MyAppendTailList geschrieben wird, die AppendTailList ähnelt, den ListToAppend-Parameter jedoch als Zeiger auf einen Listenkopf anstatt als Zeiger auf den ersten Eintrag in einer (headless) Liste behandelt. Im Gegensatz zu AppendTailList vermeidet die MyAppendTailList Funktion das Einschließen der LIST_ENTRY Struktur, auf die der ListToAppend-Parameter verweist, in die Einträge, die an die Liste angefügt werden, auf die der ListHead-Parameter verweist.

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);
    }
}

Die MyAppendTailList Funktion in diesem Codebeispiel behandelt sowohl die Parameter ListHead als auch ListToAppend als Zeiger auf Listenköpfe. Wenn diese Funktion zurückgibt, ist die Liste, auf die von ListToAppend verwiesen wird, leer. Das heißt, es besteht aus einem Listenkopf, der keine zugeordneten Listeneinträge enthält. Alle Einträge, die ursprünglich in dieser Liste enthalten waren, wurden an die Liste angefügt, auf die von ListHead verwiesen wird.

Anforderungen

Anforderung Wert
Zielplattform Desktop
Kopfzeile wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
IRQL Beliebige Ebene (siehe Abschnitt "Hinweise")

Weitere Informationen

InitializeListHead

InsertTailList

LIST_ENTRY

RemoveEntryList