AppendTailList-Funktion (wdm.h)

Artikel
07.02.2025

Die AppendTailList- Routine fügt eine doubly verknüpfte Liste LIST_ENTRY Strukturen an den Schwanz einer anderen doubly verknüpften Liste LIST_ENTRY Strukturen an.

Syntax

C++

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

Parameter

[in, out] ListHead

Ein Zeiger auf den Kopf der Liste, auf die die Liste durch ListToAppend- verweist, wird angefügt. Dieser Parameter muss ein gültiger, nicht NULL-Zeiger 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 durch 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

Nichts

Bemerkungen

Diese Routine erstellt eine Liste, die alle kombinierten Einträge aus der Eingabe ListHead- und ListToAppend--Listen 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 ListToAppend-Parameter 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 diesem Zusammenhang entspricht AppendTailList- nicht der Konvention, gefolgt von den anderen doubly verknüpften Listenroutinen, die die LIST_ENTRY Struktur verwenden. In diesen anderen Routinen verweist ein Parameter, der eine Liste darstellt, auf den Listenkopf anstelle des ersten Eintrags in der Liste. Wenn Ihr Treibercode einen Listenkopf verwendet, um die anzufügende Liste darzustellen, muss der Listenkopf aus dieser Liste entfernt werden, bevor die Liste als ListToAppend Parameter übergeben wird, um AppendTailList-. Ein Codebeispiel, das zeigt, wie dieser Listenkopf entfernt wird, finden Sie unter "Beispiele".

AppendTailList- kann verwendet werden, um einen einzelnen Eintrag am Ende einer Liste einzufügen, aber die Flink- und Blink Elemente der LIST_ENTRY-Struktur, auf die durch ListToAppend verwiesen wird, müssen zuerst initialisiert werden, in der Regel durch Aufrufen der InitializeListHead Routine. Im Gegensatz dazu erfordert die InsertTailList- Routine nicht die Flink- und Blink Member der LIST_ENTRY Struktur, auf die der Entry Parameter verweist, vor dem Aufruf InsertTailList initialisiert zu 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 Mitglieder eines LIST_ENTRYzugreifen, aber die Mitglieder müssen nur von den systemroutinen aktualisiert werden, die zu diesem Zweck bereitgestellt werden.

Informationen zur Verwendung dieser Routine bei der Implementierung einer doubly verknüpften Liste finden Sie unter Singly and Doubly Linked Lists.

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

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie eine Funktion mit dem Namen MyAppendTailList geschrieben wird, die AppendTailList-ähnelt, die jedoch den ListToAppend-Parameter als Zeiger auf einen Listenkopf anstatt als Zeiger auf den ersten Eintrag in einer (kopflosen) Liste behandelt. Im Gegensatz zu AppendTailList-verhindert die MyAppendTailList-Funktion, dass die LIST_ENTRY Struktur, auf die durch den parameter ListToAppend in den Einträgen verwiesen wird, auf die durch den ListHead Parameter verwiesen wird, eingeschlossen wird.

C++

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 ListHead- als auch ListToAppend- Parameter als Zeiger auf Listenköpfe. Wenn diese Funktion zurückgegeben wird, ist die Liste, auf die ListToAppen d verweist, leer; das heißt, sie besteht aus einem Listenkopf, der keine zugehörigen Listeneinträge enthält. Alle Einträge, die ursprünglich in dieser Liste enthalten waren, wurden an die Liste angefügt, auf die von ListHeadverwiesen wurde.