AppendTailList 函数（wdm.h）

2025-02-07

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 可用于在列表尾部插入单个条目，但 Flink 和 BlinkLIST_ENTRY 结构的成员 ListToAppend 必须首先初始化-通常，通过调用 InitializeListHead 例程。相比之下，InsertTailList 例程不需要 Flink 和 BlinkLIST_ENTRY 结构的成员，Entry 参数在 InsertTailList 调用之前初始化。因此，InsertTailList 可能更方便地用于在列表尾部插入单个条目。

驱动程序可以访问 Flink 和 BlinkLIST_ENTRY成员，但成员必须仅由系统例程进行更新才能实现此目的。

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

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

例子

下面的代码示例演示如何编写一个名为 MyAppendTailList 的函数，该函数类似于 AppendTailList，但将 ListToAppend 参数视为指向列表头的指针，而不是作为指向（headless）列表中的第一个条目的指针。与 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指向的列表中。