Fonction RtlInitializeGenericTable (ntddk.h)
La routine RtlInitializeGenericTable initialise une table générique.
Syntaxe
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
);
Paramètres
[out] Table
Pointeur vers une mémoire tampon allouée à l’appelant, qui doit avoir au moins une taille d’octets (RTL_GENERIC_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_GENERIC_COMPARE_ROUTINE) (
__in struct _RTL_GENERIC_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 GenericTable qui appellent CompareRoutine prennent un pointeur de mémoire tampon en tant que paramètre, qui est passé à son 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_GENERIC_ALLOCATE_ROUTINE) (
__in struct _RTL_GENERIC_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 GenericTable . Notez qu’en raison de cette « mémoire supplémentaire », les routines fournies par l’appelant ne doivent pas accéder aux premiers octets (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) 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_GENERIC_FREE_ROUTINE) (
__in struct _RTL_GENERIC_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 GenericTable 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 RtlInitializeGenericTable 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 RtlInitializeGenericTable pour initialiser la table générique avant d’utiliser toute autre rtl... Routines GenericTable 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 GenericTable 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’é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.
Par défaut, le système d’exploitation utilise des arborescences de lecture pour implémenter des tables génériques. Dans certaines circonstances, les opérations sur un arbre de jeu rendent l’arbre profond et étroit et peut même le transformer en une ligne droite. Les arbres très profonds dégradent les performances des recherches. Vous pouvez garantir une implémentation d’arborescence plus équilibrée et moins profonde des tables génériques à l’aide des arborescences Adelson-Velsky/Landis (AVL). Si vous souhaitez configurer les routines de table génériques 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`
Si vous souhaitez utiliser des tables AVL et si RTL_USE_AVL_TABLES n’est pas défini, vous devez utiliser la forme AVL des routines de table génériques. Par exemple, utilisez la routine RtlInitializeGenericTableAvl au lieu de RtlInitializeGenericTable. RtlInitializeGenericTableAvl retourne une structure de table RTL_AVL_TABLE initialisée dans la mémoire tampon vers laquelle pointe le paramètre Table . Dans l’appel à RtlInitializeGenericTableAvl, l’appelant doit passer une routine de rappel de comparaison de type PRTL_AVL_COMPARE_ROUTINE, une routine de rappel d’allocation de type PRTL_AVL_ALLOCATE_ROUTINE et une routine de rappel de relocalisation de type PRTL_AVL_FREE_ROUTINE au lieu des routines similaires PRTL_GENERIC_Xxx.
Les appelants de RtlInitializeGenericTable doivent être en cours d’exécution sur IRQL <= DISPATCH_LEVEL. Notez que si Rtl... Les routines GenericTable 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) |