Функция AppendTailList (wdm.h)

Подпрограмма AppendTailList добавляет список LIST_ENTRY структур в две части списка LIST_ENTRY структур.

Синтаксис

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

Параметры

[in, out] ListHead

Указатель на заголовок списка, к которому добавляется список, на который указывает ListToAppend . Этот параметр должен быть допустимым указателем, не имеющим значения NULL, на структуру LIST_ENTRY , являющуюся головой списка. Этот список может быть пустым.

[in, out] ListToAppend

Указатель на первую запись в списке для добавления в список, на который указывает ListHead. Этот параметр должен быть допустимым указателем, не имеющим значения NULL, на структуру LIST_ENTRY , которая является первой записью в списке без заголовка. Дополнительные сведения см. в подразделе "Примечания".

Возвращаемое значение

None

Remarks

Эта подпрограмма создает список, содержащий все объединенные записи из входных списков ListHead и ListToAppend . Когда подпрограмма возвращается, структура LIST_ENTRY , на которую указывает параметр ListHead , является головой результирующего объединенного списка. Структура LIST_ENTRY , на которую указывает параметр ListToAppend , является записью в итоговом объединенном списке.

Вызывающий объект задает параметр ListToAppend , указывающий на первую запись в добавляемом списке. В этом отношении AppendTailList не соответствует соглашению, за которым следуют другие процедуры списков с удвоением, использующие структуру LIST_ENTRY . В этих других подпрограммах параметр, представляющий список, указывает на голову списка, а не на первую запись в списке. Если код драйвера использует голову списка для представления добавляемого списка, необходимо удалить ее из этого списка, прежде чем список будет передан в качестве параметра ListToAppend в AppendTailList. Пример кода, показывающий, как удалить эту голову списка, см. в разделе Примеры.

AppendTailList можно использовать для вставки одной записи в конце списка, но элементы Flink и Blinkструктуры LIST_ENTRY , на которую указывает ListToAppend , необходимо сначала инициализировать, обычно путем вызова подпрограммы InitializeListHead . В отличие от этого, подпрограмме InsertTailList не требуется инициализировать элементы Flink и Blinkструктуры LIST_ENTRY , на которую указывает параметр Entry , перед вызовом InsertTailList . По этой причине insertTailList может быть удобнее использовать для вставки одной записи в конце списка.

Драйвер может получить доступ к элементам Flink и BlinkLIST_ENTRY, но эти элементы должны обновляться только системными подпрограммами, предоставляемыми для этой цели.

Сведения об использовании этой процедуры при реализации списка с удвоениями см. в разделе Singly и Doubly Linked Списки.

Вызывающие функции AppendTailList могут выполняться в любой среде IRQL. Если метод AppendTailList вызывается в IRQL >= DISPATCH_LEVEL, хранилище для записей списка должно находиться в памяти.

Примеры

В следующем примере кода показано, как написать функцию с именем MyAppendTailList , похожую на AppendTailList, но рассматривающую параметр ListToAppend как указатель на голову списка, а не как указатель на первую запись в списке (без головного). В отличие от AppendTailList, MyAppendTailList функция избегает включения структуры LIST_ENTRY , на которую указывает параметр ListToAppend , в записи, которые добавляются в список, на который указывает параметр 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);
    }
}

Функция MyAppendTailList в этом примере кода рассматривает параметры ListHead и ListToAppend как указатели на заголовки списка. При возврате этой функции список, на который указывает ListToAppend , пуст; то есть он состоит из заголовка списка без связанных записей списка. Все записи, которые были изначально в этом списке, были добавлены в список, на который указывает ListHead.

Требования

См. также раздел

InitializeListHead

InsertTailList

LIST_ENTRY

RemoveEntryList