Función RtlInitializeGenericTable (ntddk.h)

La rutina RtlInitializeGenericTable inicializa una tabla genérica.

Sintaxis

NTSYSAPI VOID RtlInitializeGenericTable(
  [out]          PRTL_GENERIC_TABLE            Table,
  [in]           PRTL_GENERIC_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_GENERIC_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_GENERIC_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                         TableContext
);

Parámetros

[out] Table

Puntero a un búfer asignado por el autor de la llamada, que debe tener al menos sizeof(RTL_GENERIC_TABLE) bytes de tamaño, para contener la estructura de tabla genérica inicializada.

[in] CompareRoutine

Punto de entrada de una rutina de devolución de llamada de comparación, declarada de la siguiente manera:

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_GENERIC_COMPARE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    ); 

Los parámetros CompareRoutine son los siguientes:

Tabla (CompareRoutine)

Puntero a la tabla genérica.

FirstStruct

Puntero al primer elemento que se va a comparar.

SecondStruct

Puntero al segundo elemento que se va a comparar.

CompareRoutine debe realizar un seguimiento estricto de la ordenación de todos los elementos de la tabla genérica para que pueda identificar cualquier elemento determinado. La estructura definida por el autor de la llamada para los datos de elemento normalmente incluye un miembro cuyo valor es único y se puede usar como clave de ordenación. Todo Rtl... Las rutinas genericTable que llaman a CompareRoutine toman un puntero de búfer como parámetro, que se pasa a su vez a CompareRoutine. El búfer contiene un valor de clave proporcionado por el autor de la llamada para que coincida con compareRoutine con la clave del elemento que se está buscando.

Dados dos valores de clave de este tipo, CompareRoutine devuelve GenericLessThan, GenericGreaterThan o GenericEqual.

[in] AllocateRoutine

Un punto de entrada de una rutina de devolución de llamada de asignación, declarada de la siguiente manera:

PVOID
(*PRTL_GENERIC_ALLOCATE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in CLONG  ByteSize
    );

Los parámetros AllocateRoutine son los siguientes:

Tabla (AllocateRoutine)

Puntero a la tabla genérica.

ByteSize

Número de bytes que se van a asignar.

Para cada nuevo elemento, se llama a AllocateRoutine para asignar memoria para los datos proporcionados por el autor de la llamada más alguna memoria adicional para su uso por el Rtl... Rutinas de GenericTable . Tenga en cuenta que, debido a esta "memoria adicional", las rutinas proporcionadas por el autor de la llamada no deben tener acceso a los primeros bytes (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) de ningún elemento de la tabla genérica.

[in] FreeRoutine

Un punto de entrada de una rutina de devolución de llamada de desasignación, declarada como se indica a continuación:

VOID
(*PRTL_GENERIC_FREE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in PVOID  Buffer
    );

Los parámetros FreeRoutine son los siguientes:

Tabla (FreeRoutine)

Puntero a la tabla genérica.

Buffer

Puntero al elemento que se está eliminando.

Rtl... Las rutinas genericTable llaman a FreeRoutine para desasignar la memoria de los elementos que se van a eliminar de la tabla genérica. FreeRoutine es lo contrario de AllocateRoutine.

[in, optional] TableContext

Puntero opcional a un contexto proporcionado por el autor de la llamada para la tabla genérica. Este parámetro puede ser NULL.

Valor devuelto

None

Observaciones

Los sistemas de archivos llaman a RtlInitializeGenericTable para inicializar una tabla genérica para almacenar datos específicos del sistema de archivos, como la información de búsqueda de nombres para los archivos abiertos actualmente. El criterio de ordenación, la estructura y el contenido de los elementos se definen por el autor de la llamada.

Los sistemas de archivos deben llamar a RtlInitializeGenericTable para inicializar la tabla genérica antes de usar cualquier otro rtl... Rutinas genericTable en la nueva tabla genérica. La estructura de tabla genérica inicializada debe considerarse opaca.

Llamadores del 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 fin.

Se llama a CompareRoutine proporcionado por el autor de la llamada antes de AllocateRoutine para buscar una ubicación adecuada en la que se debe insertar un nuevo elemento. También se llama a CompareRoutine antes de que FreeRoutine busque un elemento que se va a eliminar.

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 sea 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 desea usar tablas AVL y 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 RtlInitializeGenericTableAvl en lugar de RtlInitializeGenericTable. RtlInitializeGenericTableAvl devuelve una estructura de tabla RTL_AVL_TABLE inicializada en el búfer al que apunta el parámetro Table . En la llamada a RtlInitializeGenericTableAvl, el autor de la llamada debe pasar una rutina de devolución de llamada de comparación con tipo PRTL_AVL_COMPARE_ROUTINE, una rutina de devolución de llamada de asignación con tipo PRTL_AVL_ALLOCATE_ROUTINE y una rutina de devolución de llamada de desasignación con tipo PRTL_AVL_FREE_ROUTINE en lugar de las rutinas con tipo PRTL_GENERIC_Xxx similares.

Los autores de llamadas de RtlInitializeGenericTable deben ejecutarse en IRQL <= DISPATCH_LEVEL. Tenga en cuenta que si Rtl... Las rutinas GenericTable se usarán en irQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine y FreeRoutine deben ser código no paginable y AllocateRoutine debe asignar memoria del grupo no paginado.

Requisitos

Consulte también

ExInitializeFastMutex

RtlDeleteElementGenericTable

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable

RtlInsertElementGenericTable

RtlLookupElementGenericTable

RtlNumberGenericTableElements