Función RtlInsertElementGenericTableAvl (ntddk.h)
La rutina RtlInsertElementGenericTableAvl agrega una nueva entrada a una tabla genérica.
Sintaxis
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parámetros
[in] Table
Puntero a una tabla genérica de Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE) inicializada por una llamada a RtlInitializeGenericTableAvl.
[in] Buffer
Búfer asignado por el autor de la llamada que contiene los datos de usuario que se van a copiar en el nuevo elemento. Para obtener más información, vea RtlInitializeGenericTableAvl.
[in] BufferSize
Tamaño en bytes de datos en Búfer.
[out, optional] NewElement
En la salida, un valor true significa que la inserción del nuevo elemento en la tabla genérica se realizó correctamente. Un valor false significa que se produjo un error en la inserción.
Valor devuelto
RtlInsertElementGenericTableAvl devuelve un puntero a los datos de usuario de la entrada recién insertada o los datos de usuario de una entrada coincidente que ya está en la tabla genérica. Si no se encuentra ninguna entrada coincidente, pero RtlInsertElementGenericTableAvl no puede insertar la nueva entrada (por ejemplo, porque se produce un error en AllocateRoutine ), RtlInsertElementGenericTableAvl devuelve NULL.
Comentarios
Para insertar una entrada, RtlInsertElementGenericTableAvl llama a CompareRoutine y AllocateRoutine que se registraron cuando RtlInitializeGenericTableAvl inicializó la tabla genérica. Después de insertar la nueva entrada, RtlInsertElementGenericTableAvl reequilibró el árbol de vínculos de AVL.
Cuando se inserta una nueva entrada en la tabla, sus datos se copian del búfer en la nueva entrada. Por lo tanto, el puntero devuelto por RtlInsertElementGenericTableAvl nunca es igual a Buffer.
Si compareRoutine del autor de la llamada devuelve GenericEqual, se supone que los datos de Buffer duplican los datos de una entrada existente en la tabla genérica. En este caso, RtlInsertElementGenericTableAvl no agrega la nueva entrada (y, por tanto, no llama a AllocateRoutine), porque una tabla genérica no puede tener entradas duplicadas.
Si ya existe una entrada coincidente en la tabla genérica, RtlInsertElementGenericTableAvl devuelve un puntero a los datos de la entrada existente y establece NewElement en FALSE.
Si no hay ninguna entrada coincidente en la tabla, la rutina RtlInsertElementGenericTableAvl asigna espacio suficiente para los datos de usuario de la nueva entrada (BufferSize) más los vínculos asociados a la nueva entrada. Por lo tanto, el número total de bytes será al menos BufferSize sizeof + (RTL_BALANCED_LINKS). El llamador no debe usar los primeros bytes sizeof(RTL_BALANCED_LINKS) de la memoria que asigna AllocateRoutine.
Llamadores de Rtl.. Las rutinas GenericTableAvl son responsables de sincronizar exclusivamente el acceso a la tabla genérica. Una exclusión mutua rápida exclusiva es el mecanismo de sincronización más eficaz que se usará para este fin.
De forma predeterminada, el sistema operativo usa árboles de reproducción para implementar tablas genéricas, pero la rutina RtlInsertElementGenericTableAvl solo funciona con árboles Adelson-Velsky/Landis (AVL). Para configurar las rutinas de tabla genéricas para usar árboles AVL en lugar de reproducir árboles en el controlador, inserte la siguiente instrucción define en un archivo de encabezado común antes de incluir Ntddk.h:
#define RTL_USE_AVL_TABLES 0
Si no se define RTL_USE_AVL_TABLES, debe usar el formato AVL de las rutinas de tabla genéricas. Por ejemplo, use la rutina RtlInsertElementGenericTableAvl en lugar de RtlInsertElementGenericTable. En la llamada a RtlInsertElementGenericTableAvl, el autor de la llamada debe pasar una estructura de tabla de RTL_AVL_TABLE en lugar de RTL_GENERIC_TABLE.
Los autores de llamadas de RtlInsertElementGenericTableAvl deben ejecutarse en IRQL < DISPATCH_LEVEL si alguna de las condiciones siguientes contiene:
- La memoria asignada por el autor de la llamada en la tabla o en el búfer es paginable.
- CompareRoutine o AllocateRoutine proporcionado por el autor de la llamada contiene código paginable.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows XP. |
| Plataforma de destino | Universal |
| Encabezado | ntddk.h (include Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (consulte la sección Comentarios) |