Fonction RtlEnumerateGenericTableLikeADirectory (ntddk.h)
La routine RtlEnumerateGenericTableLikeADirectory retourne les éléments d’une table générique, un par un, dans l’ordre de classement.
Syntaxe
NTSYSAPI PVOID RtlEnumerateGenericTableLikeADirectory(
[in] PRTL_AVL_TABLE Table,
[in, optional] PRTL_AVL_MATCH_FUNCTION MatchFunction,
[in, optional] PVOID MatchData,
[in] ULONG NextFlag,
[in, out] PVOID *RestartKey,
[in, out] PULONG DeleteCount,
[in] PVOID Buffer
);
Paramètres
[in] Table
Pointeur vers la table Adelson-Velsky/Landis (RTL_AVL_TABLE) qui sera énumérée.
[in, optional] MatchFunction
Fonction de correspondance qui détermine les entrées à retourner. S’il n’est pas spécifié, tous les nœuds sont retournés.
[in, optional] MatchData
Données à passer à la fonction de correspondance.
[in] NextFlag
Si *RestartKey n’est pas NULL, une valeur de TRUE indique que l’énumération ignore un élément. Si FALSE l’énumération reprend là où elle s’est arrêtée dans l’appel précédent pour RtlEnumerateGenericTableLikeADirectory. Si *RestartKey est NULL, une valeur de TRUE indique RtlEnumerateGenericTableLikeADirectory de retourner l’entrée suivante dans l’arborescence après l’entrée qui correspond aux données dans Tampon. Une valeur de FALSE indique à RtlEnumerateGenericTableLikeADirectory de retourner l’entrée dans l’arborescence qui correspond aux données dans Tampon.
[in, out] RestartKey
Valeur qui détermine où commencer ou reprendre l’énumération des éléments de table génériques. Si *RestartKey est NULL, l’énumération commence ou reprend à partir de la position décrite dans tampon. S’il n'NULL, l’énumération reprend à partir du point que RestartKey indique. Au retour, la RestartKey contient une valeur qui indique l’emplacement dans l’arborescence où l’énumération est désactivée. Lors de l’appel suivant pour RtlEnumerateGenericTableLikeADirectory appelant doit transmettre la même valeur pour informer RtlEnumerateGenericTableLikeADirectory où reprendre l’énumération. L’exemple de code suivant illustre comment procéder :
NextFlag = FALSE;
RestartKey = NULL;
DeleteCount = 0;
// Initialize Buffer for start/resume point
Buffer = ...
for (ptr = NULL; ptr != NULL; ) {
// Value returned in RestartKey will be passed back in
// on following call (iteration):
ptr = RtlEnumerateGenericTableLikeADirectory(
&MyTable, NULL, NULL, TRUE, &RestartKey,
&DeleteCount, &Buffer, sizeof(LONG) );
...
// The value output in RestartKey will still be in
// RestartKey when the
// RtlEnumerationGenericTableLikeADirectory routine
// is called in the next iteration of this loop.
// This ensures that the enumeration will pick up
// where it left off.
}
Si un nœud est supprimé de l’arborescence entre les appels à RtlEnumerateGenericTableLikeADirectory, l’énumération reprend de la position dans l’arborescence décrite dans tampon, quelle que soit la valeur de *RestartKey.
[in, out] DeleteCount
En sortie, valeur qui indique le nombre actuel d’entrées supprimées de la table. L’appelant doit renvoyer cette valeur lors de l’appel suivant à RtlEnumerateGenericTableLikeADirectory. Cette valeur aide la routine RtlEnumerateGenericTableLikeADirectory déterminer si des suppressions de la table se sont produites entre les appels à RtlEnumerateGenericTableLikeADirectory. Si des suppressions se sont produites, l’énumération reprend avec l’entrée de table qui correspond aux données dans tampon, et non avec l’entrée de table indiquée par RestartKey. Si *RestartKey est NULL, ce paramètre n’a aucun effet sur l’énumération.
[in] Buffer
Expression clé qui détermine où commencer l’énumération, quand *RestartKey est null. L’appelant peut passer une clé enregistrée qui correspond à une entrée particulière dans la table et l’énumération commence à l’entrée spécifiée par la clé enregistrée, fournie *RestartKey est NULL et NextFlag est FALSE. Pour renvoyer la clé qui suit immédiatement une clé enregistrée, passez la clé ici, définissez *RestartKey sur NULL et NextFlag sur TRUE. Si la clé enregistrée a été supprimée, l’énumération commence par la clé correspondante suivante.
Valeur de retour
La routine RtlEnumerateGenericTableLikeADirectory retourne un pointeur vers une structure définie par l’utilisateur associée à l’élément de table suivant dans l’énumération. S’il n’y a plus de nouveaux éléments à retourner, la valeur de retour est NULL.
Remarques
La routine RtlEnumerateGenericTableLikeADirectory fournit un moyen sûr d’énumérer une table générique entre les opérations d’insertion et de suppression mélangées. À compter du premier nom de clé correspondant, RtlEnumerateGenericTableLikeADirectory retourne chaque nom dans la table exactement une fois, sauf si le nom a été inséré ou supprimé pendant l’énumération. Lorsqu’un nom de clé est inséré ou supprimé pendant une énumération (c’est-à-dire entre les appels à RtlEnumerateGenericTableLikeADirectory) il peut ou non être inclus dans l’énumération. Si ces noms sont inclus dépend de l’état du nom lorsque RtlEnumerateGenericTableLikeADirectory traite la plage de répertoires dans laquelle le nom est trouvé.
Vous pouvez utiliser quatre routines pour énumérer une table générique :
Par défaut, le système d’exploitation utilise des arborescences de lecture pour implémenter des tables génériques, mais l'RtlEnumerateGenericTableLikeADirectory routine fonctionne uniquement avec les arborescences Adelson-Velsky/Landis (AVL). Pour configurer les routines de table génériques afin d’utiliser des arborescences AVL au lieu de les exécuter 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 RTL_USE_AVL_TABLES n’est pas défini, vous devez utiliser la forme AVL des routines de table générique.
Les appelants de RtlEnumerateGenericTableLikeADirectory doivent s’exécuter au <IRQL = APC_LEVEL si l’une des conditions suivantes est conservée :
La mémoire allouée par l’appelant à table ou à tampon est paginable.
L’appelant MatchFunction contient du code paginable.
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 | <= APC_LEVEL (voir la section Remarques) |