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 par l’appelant, qui doit être au moins taille de(RTL_GENERIC_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_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.
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... GenericTable routines qui appellent le CompareRoutine prendre un pointeur de mémoire tampon en tant que paramètre, qui est passé à son tour au 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_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.
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... Routines GenericTable. Notez que, 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.
Tampon
Pointeur vers l’élément en cours de suppression.
Rtl... GenericTable routines appellent le FreeRoutine pour libérer de la mémoire des éléments à supprimer 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 RtlInitializeGenericTable 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 RtlInitializeGenericTable pour initialiser la table générique avant d’utiliser d’autres Rtl... GenericTable 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... GenericTable 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.
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 ligne droite. Des arbres très profonds dégradent les performances des recherches. Vous pouvez garantir une implémentation d’arborescence plus équilibrée et plus superficielle des tables génériques à l’aide d’arbres Adelson-Velsky/Landis (AVL). Si vous souhaitez configurer les routines de table générique 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érique. Par exemple, utilisez la routine RtlInitializeGenericTableAvl au lieu de RtlInitializeGenericTable. RtlInitializeGenericTableAvl retourne une structure de table d'RTL_AVL_TABLE initialisée dans la mémoire tampon à laquelle le Table points de paramètre. Dans l’appel à RtlInitializeGenericTableAvl, l’appelant doit passer une routine de rappel de comparaison PRTL_AVL_COMPARE_ROUTINE typée, une routine de rappel d’allocation PRTL_AVL_ALLOCATE_ROUTINE typée et une routine de rappel de désallocation PRTL_AVL_FREE_ROUTINE typée au lieu de la routine de rappel PRTL_GENERIC_Xxxsimilaire.
Les appelants de RtlInitializeGenericTable doivent s’exécuter à l'<IRQL = DISPATCH_LEVEL. Notez que si Rtl... Les routines GenericTable doivent être utilisées au 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) |