Función RtlInitializeGenericTableAvl (ntddk.h)

Artículo
02/26/2024

La rutina RtlInitializeGenericTableAvl inicializa una tabla genérica mediante árboles Adelson-Velsky/Landis (AVL).

Sintaxis

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_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 ser al menos sizeof(RTL_AVL_TABLE) bytes de tamaño, para contener la estructura de tabla genérica inicializada.

[in] CompareRoutine

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

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_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 del orden 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 GenericTableAvl 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_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_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 rtl... Rutinas GenericTableAvl . 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_BALANCED_LINKS) 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 de la siguiente manera:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_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 va a eliminar.

Rtl... Las rutinas GenericTableAvl llaman a FreeRoutine para desasignar memoria para que los elementos se eliminen de la tabla genérica. FreeRoutine es el opuesto a 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 RtlInitializeGenericTableAvl 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 están definidos por el autor de la llamada.

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

Llamadores del 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 propósito.

Se llama a CompareRoutine proporcionado por el autor de la llamada antes de que AllocateRoutine busque 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.

La rutina RtlInitializeGenericTableAvl asigna explícitamente una tabla genérica que usa árboles AVL. Uso de esta rutina y el otro Rtl... Las rutinas GenericTableAvl son necesarias cuando se desean tablas basadas en árbol de AVL y RTL_USE_AVL_TABLES no se definen antes de incluir Ntddk.h.

Si desea configurar las rutinas de tabla genéricas, Rtl... GenericTable, 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`

Los autores de llamadas de RtlInitializeGenericTableAvl deben ejecutarse en IRQL <= DISPATCH_LEVEL. Tenga en cuenta que si Rtl... Las rutinas GenericTableAvl 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

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