Função AppendTailList (wdm.h)

A rotina AppendTailList acrescenta uma lista duplamente vinculada de estruturas LIST_ENTRY à parte final de outra lista duplamente vinculada de estruturas LIST_ENTRY .

Sintaxe

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

Parâmetros

[in, out] ListHead

Um ponteiro para o cabeçalho da lista à qual a lista apontada por ListToAppend deve ser acrescentada. Esse parâmetro deve ser um ponteiro não NULL válido para a estrutura LIST_ENTRY que é o cabeçalho de uma lista. Essa lista pode estar vazia.

[in, out] ListToAppend

Um ponteiro para a primeira entrada na lista a ser acrescentada à lista apontada por ListHead. Esse parâmetro deve ser um ponteiro não NULL válido para a estrutura LIST_ENTRY que é a primeira entrada em uma lista sem periféricos. Para obter mais informações, consulte Comentários.

Retornar valor

Nenhum

Comentários

Essa rotina constrói uma lista que contém todas as entradas combinadas das listas ListHead e ListToAppend de entrada. Quando a rotina retorna, a estrutura LIST_ENTRY apontada pelo parâmetro ListHead é o cabeçalho da lista combinada resultante. A estrutura LIST_ENTRY apontada pelo parâmetro ListToAppend é uma entrada na lista combinada resultante.

O chamador define o parâmetro ListToAppend para apontar para a primeira entrada na lista a ser acrescentada. Nesse sentido, AppendTailList não está em conformidade com a convenção seguida pelas outras rotinas de lista duplamente vinculadas que usam a estrutura LIST_ENTRY . Nessas outras rotinas, um parâmetro que representa uma lista aponta para o cabeçalho da lista em vez de para a primeira entrada na lista. Se o código do driver usar um cabeçalho de lista para representar a lista a ser acrescentada, o cabeçalho da lista deverá ser removido dessa lista antes que a lista seja passada como o parâmetro ListToAppend para AppendTailList. Para obter um exemplo de código que mostra como remover esse cabeçalho de lista, consulte Exemplos.

AppendTailList pode ser usado para inserir uma única entrada na parte final de uma lista, mas os membros Flink e Blink da estrutura LIST_ENTRY apontada por ListToAppend devem primeiro ser inicializados, normalmente, chamando a rotina InitializeListHead . Por outro lado, a rotina InsertTailList não exige que os membros Flink e Blink da estrutura LIST_ENTRY apontada pelo parâmetro Entry sejam inicializados antes da chamada InsertTailList . Por esse motivo, InsertTailList pode ser mais conveniente de usar para inserir uma única entrada na parte final de uma lista.

Um driver pode acessar os membros Flink e Blink de uma LIST_ENTRY, mas os membros só devem ser atualizados pelas rotinas do sistema fornecidas para essa finalidade.

Para obter informações sobre como usar essa rotina ao implementar uma lista duplamente vinculada, consulte Singly e Doubly Linked Listas.

Os chamadores de AppendTailList podem estar em execução em qualquer IRQL. Se AppendTailList for chamado em IRQL >= DISPATCH_LEVEL, o armazenamento para as entradas da lista deverá ser residente em memória.

Exemplos

O exemplo de código a seguir mostra como escrever uma função chamada MyAppendTailList que é semelhante a AppendTailList, mas que trata o parâmetro ListToAppend como um ponteiro para um cabeçalho de lista, em vez de como um ponteiro para a primeira entrada em uma lista (sem cabeça). Ao contrário de AppendTailList, a MyAppendTailList função evita incluir a estrutura LIST_ENTRY apontada pelo parâmetro ListToAppend nas entradas acrescentadas à lista apontada pelo parâmetro 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);
    }
}

A MyAppendTailList função neste exemplo de código trata os parâmetros ListHead e ListToAppend como ponteiros para cabeçalhos de lista. Quando essa função retorna, a lista apontada por ListToAppend está vazia; ou seja, ele consiste em um cabeçalho de lista que não tem entradas de lista associadas. Todas as entradas inicialmente nesta lista foram acrescentadas à lista apontada por ListHead.

Requisitos

Confira também

InitializeListHead

InsertTailList

LIST_ENTRY

RemoveEntryList