Fonction RtlEnumerateGenericTableLikeADirectory (ntddk.h)

Article
02/26/2024

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 (AVL) (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’a pas la valeur NULL, la valeur TRUE indique que l’énumération ignore un élément. Si la valeur EST FALSE , l’énumération reprend là où elle s’était arrêté lors de l’appel précédent à RtlEnumerateGenericTableLikeADirectory. Si RestartKey a la valeur NULL, la valeur TRUE indique à RtlEnumerateGenericTableLikeADirectory de retourner l’entrée suivante dans l’arborescence après l’entrée qui correspond aux données dans Buffer. La valeur FALSE indique à RtlEnumerateGenericTableLikeADirectory de retourner l’entrée dans l’arborescence qui correspond aux données dans Buffer.

[in, out] RestartKey

Valeur qui détermine où commencer ou reprendre l’énumération des éléments de table génériques. Si RestartKey a la valeur NULL, l’énumération commence ou reprend à partir de la position décrite dans Mémoire tampon. Si ce n’est pas NULL, l’énumération reprend à partir du point indiqué par RestartKey . Au retour, restartKey contient une valeur qui indique l’emplacement dans l’arborescence où l’énumération a été désactivée. Lors de l’appel suivant à RtlEnumerateGenericTableLikeADirectory , l’appelant doit renvoyer la même valeur pour informer RtlEnumerateGenericTableLikeADirectory où reprendre l’énumération. L’exemple de code suivant montre 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 à partir de la position dans l’arborescence décrite dans Mémoire tampon, quelle que soit la valeur de RestartKey.

[in, out] DeleteCount

Sur la 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 permet à la routine RtlEnumerateGenericTableLikeADirectory de 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 de la mémoire tampon, et non avec l’entrée de table indiquée par RestartKey. Si RestartKey a lavaleur NULL, ce paramètre n’a aucun effet sur l’énumération..

[in] Buffer

Expression clé qui détermine où commencer l’énumération, lorsque RestartKey a la valeur 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, à condition que RestartKey ait la valeur NULL et Que NextFlag ait la valeur FALSE. Pour retourner la clé qui suit immédiatement une clé enregistrée, transmettez 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 retournée

La routine RtlEnumerateGenericTableLikeADirectory retourne un pointeur vers une structure définie par l’utilisateur qui est associé à l’élément table suivant dans l’énumération. S’il n’y a plus de nouveaux éléments à renvoyer, 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 mixtes. À compter du premier nom de clé mis en correspondance, RtlEnumerateGenericTableLikeADirectory retourne chaque nom de 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. L’inclusion de tels noms 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 la routine RtlEnumerateGenericTableLikeADirectory fonctionne uniquement avec les arborescences Adelson-Velsky/Landis (AVL). Pour configurer les routines de table génériques afin d’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 RTL_USE_AVL_TABLES n’est pas défini, vous devez utiliser la forme AVL des routines de table génériques.

Les appelants de RtlEnumerateGenericTableLikeADirectory doivent s’exécuter sur IRQL <= APC_LEVEL si l’une des conditions suivantes est remplie :

La mémoire allouée à l’appelant au niveau de la table ou de la mémoire tampon est paginable.
Le MatchFunction fourni par l’appelant contient du code paginable.

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	<= APC_LEVEL (voir la section Remarques)

Voir aussi

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutsplaying

RtlGetElementGenericTable