Fonction RtlInitializeGenericTableAvl (ntddk.h)

Article
02/26/2024

La routine RtlInitializeGenericTableAvl initialise une table générique à l’aide d’arborescences 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 à l’appelant, qui doit avoir au moins une taille d’octets (RTL_AVL_TABLE) 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.

CompareRoutine doit suivre strictement l’ordre de tous les éléments de la table générique afin qu’il puisse identifier un é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. Tout Rtl... Les routines GenericTableAvl qui appellent CompareRoutine prennent un pointeur de mémoire tampon en tant que paramètre, qui est passé à leur tour à CompareRoutine. La mémoire tampon contient une valeur de clé fournie par l’appelant à être mise en correspondance par CompareRoutine à la clé de l’élément recherché.

Avec deux valeurs de clé de ce type, CompareRoutine retourne GenericLessThan, GenericGreaterThan ou 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.

Taille

Nombre d'octets à allouer.

Pour chaque nouvel élément, l’objet 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 à utiliser par le Rtl... Routines GenericTableAvl . Notez qu’en raison de cette « mémoire supplémentaire », les routines fournies par l’appelant ne doivent pas accéder aux premiers octets de taille(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.

Buffer

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

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

[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

None

Remarques

Les systèmes de fichiers appellent RtlInitializeGenericTableAvl pour initialiser une table générique afin de stocker des données spécifiques au système de fichiers, telles que des informations de recherche de nom 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 toute autre rtl... Routines GenericTableAvl sur la nouvelle table générique. La structure de table générique initialisée doit être considérée comme opaque.

Les appelants de Rtl... Les routines GenericTableAvl sont chargées de synchroniser exclusivement 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’élément CompareRoutine fourni par l’appelant est appelé avant l’objet AllocateRoutine pour localiser un emplacement approprié où un nouvel élément doit être inséré. CompareRoutine est également appelé avant FreeRoutine pour localiser un élément à supprimer.

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

Si vous souhaitez configurer les routines de table génériques, Rtl... GenericTable, pour utiliser les arborescences AVL au lieu d’exécuter des arborescences 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 être en cours d’exécution à IRQL <= DISPATCH_LEVEL. Notez que si Rtl... Les routines GenericTableAvl doivent être utilisées dans IRQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine et FreeRoutine doivent toutes être du code non paginable, et l’allocationRoutine doit allouer de la mémoire à partir d’un pool non paginé.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ntddk.h (inclure Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (voir la section Remarques)