Función RtlInsertElementGenericTable (ntddk.h)

La rutina RtlInsertElementGenericTable agrega un nuevo elemento a una tabla genérica.

Sintaxis

NTSYSAPI PVOID RtlInsertElementGenericTable(
  [in]            PRTL_GENERIC_TABLE Table,
  [in]            PVOID              Buffer,
  [in]            CLONG              BufferSize,
  [out, optional] PBOOLEAN           NewElement
);

Parámetros

[in] Table

Puntero a la tabla genérica (RTL_GENERIC_TABLE). La tabla debe haberse inicializado llamando a RtlInitializeGenericTable.

[in] Buffer

Puntero a un búfer asignado por el autor de la llamada que contiene los datos que se van a copiar en el nuevo elemento. Para obtener más información, vea la descripción de RtlInitializeGenericTable.

[in] BufferSize

Número de bytes que se asignarán para los datos proporcionados por el autor de la llamada cuando se inserta el nuevo elemento.

[out, optional] NewElement

Puntero a una variable que recibe TRUE si se insertó un nuevo elemento con los datos en Buffer en la tabla genérica; o FALSE si el nuevo elemento no se ha insertado.

Valor devuelto

RtlInsertElementGenericTable devuelve un puntero a los datos asociados del elemento recién insertado, o devuelve un puntero a los datos del elemento existente si ya existe un elemento coincidente en la tabla genérica. Si no se encuentra ningún elemento coincidente, pero no se puede insertar el nuevo elemento (por ejemplo, porque se produce un error en AllocateRoutine ), RtlInsertElementGenericTable devuelve NULL.

Comentarios

Para insertar un elemento, RtlInsertElementGenericTable llama a CompareRoutine y AllocateRoutine que se registraron cuando RtlInitializeGenericTable inicializó la tabla genérica. Después de insertar el nuevo elemento, RtlInsertElementGenericTable reequilibró el árbol de vínculos de reproducción.

Cuando se inserta un nuevo elemento en la tabla, sus datos se copian de Buffer en el nuevo elemento. Por lo tanto, el puntero devuelto por RtlInsertElementGenericTable 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 un elemento existente en la tabla genérica. En este caso, RtlInsertElementGenericTable no agrega el nuevo elemento (y, por lo tanto, no llama a AllocateRoutine), porque una tabla genérica no puede tener elementos duplicados.

Si ya existe un elemento coincidente en la tabla genérica, RtlInsertElementGenericTable devuelve un puntero a los datos del elemento existente y establece NewElement en FALSE.

Autores de llamadas de Rtl.. Las rutinas genericTable 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 propósito.

De forma predeterminada, el sistema operativo usa árboles de reproducción para implementar tablas genéricas. En algunas circunstancias, las operaciones en un árbol de reproducción harán que el árbol esté profundo y estrecho e incluso puede convertirlo en una línea recta. Los árboles muy profundos degradan el rendimiento de las búsquedas. Puede garantizar una implementación de árbol más equilibrada y superficial de tablas genéricas mediante árboles Adelson-Velsky/Landis (AVL). Si desea configurar las rutinas de tabla genéricas para usar árboles AVL en lugar de árboles de reproducción 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 RtlInsertElementGenericTable deben ejecutarse en IRQL < DISPATCH_LEVEL si alguna de las condiciones siguientes contiene:

  • La memoria asignada por el autor de la llamada en Table o at Buffer es paginable.
  • CompareRoutine o AllocateRoutine proporcionado por el autor de la llamada contiene código paginable.

Requisitos

Requisito Value
Plataforma de destino Universal
Encabezado ntddk.h (incluya Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
Archivo DLL NtosKrnl.exe
IRQL < DISPATCH_LEVEL (consulte la sección Comentarios)

Consulte también

RtlDeleteElementGenericTable

RtlInitializeGenericTable