AppendTailList 函数 (wdm.h)

项目
03/08/2023

AppendTailList 例程将LIST_ENTRY结构的双链接列表追加到另一个LIST_ENTRY结构的双链接列表的末尾。

语法

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

参数

[in, out] ListHead

指向 ListToAppend 所指向的列表的标题的指针。此参数必须是指向列表头 LIST_ENTRY 结构的有效非 NULL 指针。此列表可以为空。

[in, out] ListToAppend

指向列表中要追加到 ListHead 指向的列表的第一个条目的指针。此参数必须是指向 LIST_ENTRY 结构的有效非 NULL 指针，该结构是无外设列表中的第一个条目。有关详细信息，请参阅“备注”。

返回值

无

备注

此例程构造一个列表，其中包含输入 ListHead 和 ListToAppend 列表中的所有组合条目。当例程返回时，ListHead 参数指向的LIST_ENTRY结构是生成的组合列表的头。 ListToAppend 参数指向的LIST_ENTRY结构是生成的组合列表中的一个条目。

调用方将 ListToAppend 参数设置为指向列表中要追加的第一个条目。在这方面， AppendTailList 不符合后跟使用 LIST_ENTRY 结构的其他双链接列表例程的约定。在这些其他例程中，表示列表的参数指向列表头，而不是列表中的第一个条目。如果驱动程序代码使用列表头来表示要追加的列表，则必须从此列表中删除列表头，然后列表才会作为 ListToAppend 参数传递到 AppendTailList。有关演示如何删除此列表标题的代码示例，请参阅示例。

AppendTailList 可用于在列表的末尾插入单个条目，但 ListToAppend 指向的LIST_ENTRY结构的 Flink 和 Blink 成员必须首先进行初始化，通常通过调用 InitializeListHead 例程进行初始化。相比之下，InsertTailList 例程不需要在 InsertTailList 调用之前初始化 Entry 参数指向的LIST_ENTRY结构的 Flink 和 Blink 成员。出于此原因， InsertTailList 可能更方便用于在列表末尾插入单个条目。

驱动程序可以访问LIST_ENTRY的 Flink 和 Blink 成员，但这些成员只能由为此提供的系统例程进行更新。

有关在实现双链接列表时使用此例程的信息，请参阅 Singly 和 Doubly Linked Lists。

AppendTailList 的调用方可以在任何 IRQL 上运行。如果在 IRQL >= DISPATCH_LEVEL 调用 AppendTailList，则列表条目的存储必须是内存驻留的。

示例

下面的代码示例演示如何编写一个名为 MyAppendTailList 的函数，该函数类似于 AppendTailList，但该函数将 ListToAppend 参数视为指向列表头的指针，而不是作为指向 (无头) 列表中的第一个条目的指针。与 AppendTailList 不同，MyAppendTailList函数避免在追加到 ListHead 参数指向的列表的条目中包含 ListToAppend 参数指向的 LIST_ENTRY 结构。

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

MyAppendTailList此代码示例中的函数将 ListHead 和 ListToAppend 参数视为指向列表头的指针。当此函数返回时， ListToAppend 指向的列表为空;也就是说，它由没有关联列表条目的列表头组成。最初在此列表中的所有条目都已追加到 ListHead 指向的列表。