Funzione AppendTailList (wdm.h)

Articolo
03/08/2023

La routine AppendTailList aggiunge un elenco doubly collegato di strutture LIST_ENTRY alla parte finale di un altro elenco collegato doubly di strutture LIST_ENTRY .

Sintassi

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

Parametri

[in, out] ListHead

Puntatore all'intestazione dell'elenco a cui deve essere aggiunto l'elenco a cui punta ListToAppend . Questo parametro deve essere un puntatore non NULL valido alla struttura LIST_ENTRY che rappresenta l'intestazione di un elenco. Questo elenco può essere vuoto.

[in, out] ListToAppend

Puntatore alla prima voce dell'elenco a cui aggiungere l'elenco a cui punta ListHead. Questo parametro deve essere un puntatore non NULL valido alla struttura LIST_ENTRY che rappresenta la prima voce di un elenco senza intestazione. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

nessuno

Osservazioni

Questa routine crea un elenco che contiene tutte le voci combinate degli elenchi ListHead e ListToAppend di input. Quando la routine viene restituita, la struttura LIST_ENTRY a cui punta il parametro ListHead è l'intestazione dell'elenco combinato risultante. La struttura LIST_ENTRY a cui punta il parametro ListToAppend è una voce nell'elenco combinato risultante.

Il chiamante imposta il parametro ListToAppend in modo che punti alla prima voce dell'elenco da aggiungere. A questo proposito , AppendTailList non è conforme alla convenzione seguita dalle altre routine di elenco collegate doubly che utilizzano la struttura LIST_ENTRY . In queste altre routine, un parametro che rappresenta un elenco punta all'intestazione dell'elenco anziché alla prima voce dell'elenco. Se il codice del driver usa un elenco head per rappresentare l'elenco da accodare, l'intestazione dell'elenco deve essere rimossa da questo elenco prima che l'elenco venga passato come parametro ListToAppend a AppendTailList. Per un esempio di codice che illustra come rimuovere l'intestazione dell'elenco, vedere Esempi.

AppendTailList può essere usato per inserire una singola voce nella parte finale di un elenco, ma i membri Flink e Blink della struttura LIST_ENTRY a cui punta ListToAppend devono prima essere inizializzati, in genere chiamando la routine InitializeListHead . Al contrario, la routine InsertTailList non richiede l'inizializzazione dei membri Flink e Blink della struttura LIST_ENTRY a cui punta il parametro Entry prima della chiamata a InsertTailList . Per questo motivo , InsertTailList potrebbe essere più comodo da usare per inserire una singola voce nella parte finale di un elenco.

Un driver può accedere ai membri Flink e Blink di un LIST_ENTRY, ma i membri devono essere aggiornati solo dalle routine di sistema fornite a questo scopo.

Per informazioni sull'uso di questa routine durante l'implementazione di un elenco collegato doubly, vedere Singly e Doubly Linked Elenchi.

I chiamanti di AppendTailList possono essere eseguiti in qualsiasi IRQL. Se AppendTailList viene chiamato in IRQL >= DISPATCH_LEVEL, l'archiviazione per le voci di elenco deve essere residente in memoria.

Esempio

Nell'esempio di codice seguente viene illustrato come scrivere una funzione denominata MyAppendTailList simile a AppendTailList, ma che considera il parametro ListToAppend come puntatore a un oggetto list head anziché come puntatore alla prima voce di un elenco (headless). A differenza di AppendTailList, la MyAppendTailList funzione evita di includere la struttura LIST_ENTRY a cui punta il parametro ListToAppend nelle voci aggiunte all'elenco a cui punta il parametro 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);
    }
}

La MyAppendTailList funzione in questo esempio di codice considera i parametri ListHead e ListToAppend come puntatori alle intestazioni elenco. Quando questa funzione viene restituita, l'elenco a cui punta ListToAppend è vuoto; ovvero è costituito da un elenco head senza voci di elenco associate. Tutte le voci inizialmente presenti in questo elenco sono state aggiunte all'elenco a cui punta ListHead.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
IRQL	Qualsiasi livello (vedere la sezione Osservazioni)