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 pelo 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 da 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 cabeça. Para obter mais informações, consulte Comentários.
Valor de retorno
Nenhum
Observações
Essa rotina constrói uma lista que contém todas as entradas combinadas das listas de listhead de de entrada e listToAppend. Quando a rotina é retornada, a estrutura de 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 da 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 essa cabeça de lista, consulte Exemplos.
AppendTailList pode ser usado para inserir uma única entrada na parte final de uma lista, mas os membros do Flink e Blink membros da estrutura LIST_ENTRY apontados 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 de Entrada 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 o do Flink e os membros do Blink de um 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 Listas Vinculadas Singly e Doubly.
Os chamadores de AppendTailList podem estar em execução em qualquer IRQL. Se AppendTailList for chamado em IRQL >= DISPATCH_LEVEL, o armazenamento das 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 semelhante a AppendTailList, mas que trata o parâmetro ListToAppend como um ponteiro para uma cabeça de lista em vez de como um ponteiro para a primeira entrada em uma lista (sem cabeça). Ao contrário de AppendTailList, a função MyAppendTailList evita incluir a estrutura de 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 função MyAppendTailList 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
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | wdm.h (incluem Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h) |
| IRQL | Qualquer nível (seção Ver Comentários) |