RtlInitializeGenericTableAvl, fonction (ntddk.h)

Article
02/07/2025

La routine RtlInitializeGenericTableAvl initialise une table générique à l’aide d’arbres Adelson-Velsky/Landis (AVL).

Syntaxe

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
);

Paramètres

[out] Table

Pointeur vers une mémoire tampon allouée par l’appelant, qui doit être au moins taille de(RTL_AVL_TABLE) octets, pour contenir la structure de table générique initialisée.

[in] CompareRoutine

Point d’entrée d’une routine de rappel de comparaison, déclaré comme suit :

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    );

Les paramètres CompareRoutine sont les suivants :

Table (CompareRoutine)

Pointeur vers la table générique.

FirstStruct

Pointeur vers le premier élément à comparer.

SecondStruct

Pointeur vers le deuxième élément à comparer.

Le CompareRoutine doit suivre strictement l’ordre de tous les éléments de la table générique afin qu’il puisse identifier n’importe quel élément particulier. La structure définie par l’appelant pour les données d’élément inclut généralement un membre dont la valeur est unique et peut être utilisée comme clé de tri. Tous les Rtl... GenericTableAvl routines qui appellent le CompareRoutine prendre un pointeur de mémoire tampon en tant que paramètre, qui est passé à son tour à l'CompareRoutine. La mémoire tampon contient une valeur de clé fournie par l’appelant pour être mise en correspondance par l'CompareRoutine à la clé de l’élément recherché.

Compte tenu de deux valeurs clés de ce type, le CompareRoutine retourne GenericLessThan, GenericGreaterThanou GenericEqual.

[in] AllocateRoutine

Point d’entrée d’une routine de rappel d’allocation, déclaré comme suit :

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in CLONG  ByteSize
    );

Les paramètres AllocateRoutine sont les suivants :

Table (AllocateRoutine)

Pointeur vers la table générique.

ByteSize

Nombre d’octets à allouer.

Pour chaque nouvel élément, le AllocateRoutine est appelé pour allouer de la mémoire pour les données fournies par l’appelant, ainsi que de la mémoire supplémentaire utilisée par le Rtl... GenericTableAvl routines. Notez que, en raison de cette « mémoire supplémentaire », les routines fournies par l’appelant ne doivent pas accéder aux premiers octets (RTL_BALANCED_LINKS) d’un élément de la table générique.

[in] FreeRoutine

Point d’entrée d’une routine de rappel de désallocation, déclaré comme suit :

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  Buffer
    );

Les paramètres FreeRoutine sont les suivants :

Table (FreeRoutine)

Pointeur vers la table générique.

Tampon

Pointeur vers l’élément en cours de suppression.

Rtl... GenericTableAvl routines appellent le FreeRoutine pour libérer de la mémoire pour que les éléments soient supprimés de la table générique. Le FreeRoutine est l’opposé de la Alloutine.

[in, optional] TableContext

Pointeur facultatif vers un contexte fourni par l’appelant pour la table générique. Ce paramètre peut être NULL.

Valeur de retour

Aucun

Remarques

Les systèmes de fichiers appellent RtlInitializeGenericTableAvl pour initialiser une table générique pour stocker des données spécifiques au système de fichiers, telles que des informations de recherche de noms pour les fichiers actuellement ouverts. L’ordre de tri, la structure et le contenu des éléments sont définis par l’appelant.

Les systèmes de fichiers doivent appeler RtlInitializeGenericTableAvl pour initialiser la table générique avant d’utiliser d’autres Rtl... GenericTableAvl routines sur la nouvelle table générique. La structure de table générique initialisée doit être considérée comme opaque.

Appelants du Rtl... GenericTableAvl routines sont responsables de la synchronisation exclusive de l’accès à la table générique. Un mutex rapide exclusif est le mécanisme de synchronisation le plus efficace à utiliser à cet effet.

L’appelant CompareRoutine est appelé avant le d’AllocationRoutine pour localiser un emplacement approprié auquel un nouvel élément doit être inséré. Le CompareRoutine est également appelé avant le FreeRoutine de pour localiser un élément à supprimer.

La RtlInitializeGenericTableAvl alloue explicitement une table générique qui utilise des arborescences AVL. Utilisation de cette routine et l’autre Rtl... GenericTableAvl routines est nécessaire lorsque les tables basées sur des arborescences AVL sont souhaitées et RTL_USE_AVL_TABLES n’est pas définie avant d’inclure Ntddk.h.

Si vous souhaitez configurer les routines de table générique, Rtl... GenericTable, pour utiliser des arborescences AVL plutôt que des arborescences de lecture dans votre pilote, insérez l’instruction define suivante dans un fichier d’en-tête commun avant d’inclure Ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

Les appelants de RtlInitializeGenericTableAvl doivent s’exécuter à l'<IRQL = DISPATCH_LEVEL. Notez que si Rtl... Les routines GenericTableAvl doivent être utilisées dans le DISPATCH_LEVEL IRQL, les CompareRoutine, AllocateRoutineet FreeRoutine doivent tous être du code non paginable, et le AllocateRoutine doit allouer de la mémoire à partir d’un pool non paginé.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (voir la section Remarques)