Función AppendTailList (wdm.h)

Artículo
03/08/2023

La rutina AppendTailList anexa una lista doblemente vinculada de estructuras de LIST_ENTRY a la cola de otra lista doblemente vinculada de estructuras LIST_ENTRY .

Sintaxis

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

Parámetros

[in, out] ListHead

Puntero al encabezado de la lista a la que se va a anexar la lista a la que apunta ListToAppend . Este parámetro debe ser un puntero válido que no sea NULL a la estructura LIST_ENTRY que es el encabezado de una lista. Esta lista puede estar vacía.

[in, out] ListToAppend

Puntero a la primera entrada de la lista que se va a anexar a la lista a la que apunta ListHead. Este parámetro debe ser un puntero válido que no sea NULL a la estructura LIST_ENTRY que es la primera entrada de una lista sin encabezado. Para obtener más información, vea la sección Comentarios.

Valor devuelto

None

Observaciones

Esta rutina crea una lista que contiene todas las entradas combinadas de las listas ListHead y ListToAppend de entrada. Cuando se devuelve la rutina, la estructura LIST_ENTRY a la que apunta el parámetro ListHead es el encabezado de la lista combinada resultante. La estructura de LIST_ENTRY a la que apunta el parámetro ListToAppend es una entrada de la lista combinada resultante.

El llamador establece el parámetro ListToAppend para que apunte a la primera entrada de la lista que se va a anexar. A este respecto, AppendTailList no se ajusta a la convención seguida de las otras rutinas de lista doblemente vinculadas que usan la estructura LIST_ENTRY . En estas otras rutinas, un parámetro que representa una lista apunta al encabezado de la lista en lugar de a la primera entrada de la lista. Si el código del controlador usa un encabezado de lista para representar la lista que se va a anexar, el encabezado de lista debe quitarse de esta lista antes de pasar la lista como parámetro ListToAppend a AppendTailList. Para obtener un ejemplo de código que muestre cómo quitar este encabezado de lista, vea Ejemplos.

AppendTailList se puede usar para insertar una única entrada en la cola de una lista, pero los miembros Flink y Blink de la estructura de LIST_ENTRY a la que apunta ListToAppend deben inicializarse primero, normalmente llamando a la rutina InitializeListHead . Por el contrario, la rutina InsertTailList no requiere que los miembros Flink y Blink de la estructura de LIST_ENTRY apuntado por el parámetro Entry se inicialicen antes de la llamada a InsertTailList . Por este motivo, InsertTailList puede ser más cómodo de usar para insertar una sola entrada en el final de una lista.

Un controlador puede acceder a los miembros Flink y Blink de un LIST_ENTRY, pero los miembros solo deben actualizarse por las rutinas del sistema proporcionadas para este fin.

Para obtener información sobre el uso de esta rutina al implementar una lista vinculada doblemente, consulte Singly and Duplicay Linked Listas.

Los autores de llamadas de AppendTailList se pueden ejecutar en cualquier IRQL. Si se llama a AppendTailList en IRQL >= DISPATCH_LEVEL, el almacenamiento de las entradas de lista debe ser residente en memoria.

Ejemplos

En el ejemplo de código siguiente se muestra cómo escribir una función denominada MyAppendTailList que es similar a AppendTailList, pero que trata el parámetro ListToAppend como puntero a un encabezado de lista en lugar de como puntero a la primera entrada de una lista (sin encabezado). A diferencia de AppendTailList, la MyAppendTailList función evita incluir la estructura LIST_ENTRY a la que apunta el parámetro ListToAppend en las entradas anexadas a la lista a la que apunta el 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);
    }
}

La MyAppendTailList función de este ejemplo de código trata los parámetros ListHead y ListToAppend como punteros a los encabezados de lista. Cuando se devuelve esta función, la lista a la que apunta ListToAppend está vacía; es decir, consta de un encabezado de lista que no tiene entradas de lista asociadas. Todas las entradas que se encontraban inicialmente en esta lista se han anexado a la lista a la que apunta ListHead.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluye Wdm.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
IRQL	Cualquier nivel (consulte la sección Comentarios)

Consulte también