RtlInsertElementGenericTableFullAvl, fonction (ntddk.h)
La routine RtlInsertElementGenericTableFullAvl ajoute une nouvelle entrée à une table générique.
Syntaxe
NTSYSAPI PVOID RtlInsertElementGenericTableFullAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement,
[in] PVOID NodeOrParent,
[in] TABLE_SEARCH_RESULT SearchResult
);
Paramètres
[in] Table
Pointeur vers une table Adelson-Velsky/Landis générique (RTL_AVL_TABLE) qui a été initialisée par un appel à RtlInitializeGenericTableAvl.
[in] Buffer
Mémoire tampon allouée par l’appelant qui contient les données utilisateur à copier dans le nouvel élément. Pour plus d’informations, consultez RtlInitializeGenericTableAvl.
[in] BufferSize
Taille en octets de données dans mémoire tampon.
[out, optional] NewElement
Dans la sortie, une valeur de TRUE signifie que l’insertion du nouvel élément dans la table générique a réussi. La valeur FALSE signifie que l’insertion a échoué.
[in] NodeOrParent
Résultat de recherche d’un appel précédent à RtlLookupElementGenericTableFullAvl. Cette valeur indique à la routine RtlInsertElementGenericTableFullAvl routine si l’arborescence est actuellement vide, ou si elle n’est pas vide, s’il faut insérer la nouvelle entrée à gauche ou à droite de l’entrée parente. Le paramètre SearchResult peut avoir l’une des valeurs suivantes :
TableEmptyTree
L’arborescence était vide. Le contenu de NodeOrParent n’a pas été modifié.
TableFoundNode
La routine RtlInsertElementGenericTableFullAvl a trouvé une entrée de table dont la clé correspond aux données dans Tampon. NodeOrParent contient un pointeur vers l’entrée correspondante.
TableInsertAsLeft
La routine RtlInsertElementGenericTableFullAvl n’a pas trouver une entrée de table dont la clé correspond aux données dans Tampon. Si l’entrée RtlInsertElementGenericTableFullAvl recherchée dans la table, il s’agit de l’enfant gauche de l’entrée à laquelle NodeOrParent pointe.
TableInsertAsRight
La routine RtlInsertElementGenericTableFullAvl n’a pas trouver une entrée de table dont la clé correspond aux données dans Tampon. Si l’entrée RtlInsertElementGenericTableFullAvl recherchée dans la table, il s’agit de l’enfant approprié de l’entrée à laquelle NodeOrParent pointe.
[in] SearchResult
Pointeur vers une entrée de table. Si la routine RtlInsertElementGenericTableFullAvl correspond à une entrée, NodeOrParent pointe vers l’entrée correspondante. Si la routine RtlInsertElementGenericTableFullAvl ne parvient pas à trouver une correspondance, NodeOrParent pointe vers l’entrée qui serait le parent de l’entrée qui RtlInsertElementGenericTableFullAvl routine recherchait.
Valeur de retour
RtlInsertElementGenericTableFullAvl retourne un pointeur vers les données utilisateur de l’entrée nouvellement insérée, ou les données utilisateur d’une entrée correspondante qui se trouve déjà dans la table générique. Si aucune entrée correspondante n’est trouvée, mais RtlInsertElementGenericTableFullAvl ne peut pas insérer la nouvelle entrée (par exemple, car l'AllocateRoutine échoue), RtlInsertElementGenericTableFullAvl retourne NULL.
Remarques
Pour insérer une entrée, RtlInsertElementGenericTableFullAvl appelle le CompareRoutine et AllocateRoutine qui ont été inscrits lors de l’initialisation de la table générique par RtlInitializeGenericTableAvl. Après avoir inséré la nouvelle entrée, RtlInsertElementGenericTableFullAvl rééquilibre l’arborescence des liens AVL.
Lorsqu’une nouvelle entrée est insérée dans la table, ses données sont copiées à partir de tampon dans la nouvelle entrée. Ainsi, le pointeur retourné par RtlInsertElementGenericTableFullAvl n’est jamais égal à tampon.
Si le CompareRoutine de l’appelant retourne GenericEqual, les données à mémoire tampon sont supposées dupliquer les données d’une entrée existante dans la table générique. Dans ce cas, RtlInsertElementGenericTableFullAvl n’ajoute pas la nouvelle entrée (et n’appelle donc pas le AllocateRoutine), car une table générique ne peut pas avoir d’entrées en double.
Si une entrée correspondante existe déjà dans la table générique, RtlInsertElementGenericTableFullAvl retourne un pointeur vers les données et jeux de données de l’entrée existante NewElement sur FALSE.
S’il n’existe pas déjà d’entrée correspondante dans la table,RtlInsertElementGenericTableFullAvl routine alloue suffisamment d’espace pour les données utilisateur de nouvelle entrée (BufferSize) ainsi que les liens associés à la nouvelle entrée. Ainsi, le nombre total d’octets sera au moins BufferSize + sizeof(BALANCED_LINKS). L’appelant ne doit pas utiliser la première taille (BALANCED_LINKS) octets de la mémoire que le AllocateRoutinealloue.
Appelants duRtl.. GenericTableAvl 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.
Par défaut, le système d’exploitation utilise des arborescences de jeu pour implémenter des tables génériques, mais la RtlInsertElementGenericTableFullAvl routine fonctionne uniquement avec les arbres Adelson-Velsky/Landis (AVL). Pour configurer les routines de table génériques afin d’utiliser des arborescences AVL au lieu d’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érique. Par exemple, utilisez la routine RtlInsertElementGenericTableFullAvl au lieu de RtlInsertElementGenericTableFull. Dans l’appel à RtlInsertElementGenericTableFullAvl, l’appelant doit passer une structure de table RTL_AVL_TABLE plutôt que RTL_GENERIC_TABLE.
Les appelants de RtlInsertElementGenericTableFullAvl doivent s’exécuter à l'< DISPATCH_LEVEL IRQL si l’une des conditions suivantes est conservée :
- La mémoire allouée par l’appelant à table ou à tampon est paginable.
- L’appelant CompareRoutine ou AllocateRoutine contient du code paginable.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Windows XP et versions ultérieures des systèmes d’exploitation Windows. |
| plateforme cible | Universel |
| d’en-tête | ntddk.h (include Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (voir la section Remarques) |