Fonction RtlInsertElementGenericTableAvl (ntddk.h)
La routine RtlInsertElementGenericTableAvl ajoute une nouvelle entrée à une table générique.
Syntaxe
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Paramètres
[in] Table
Pointeur vers une table Adelson-Velsky/Landis (AVL) générique (RTL_AVL_TABLE) qui a été initialisée par un appel à RtlInitializeGenericTableAvl.
[in] Buffer
Mémoire tampon allouée à 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 la mémoire tampon.
[out, optional] NewElement
En sortie, la valeur 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é.
Valeur retournée
RtlInsertElementGenericTableAvl retourne un pointeur vers les données utilisateur de l’entrée nouvellement insérée, ou les données utilisateur pour 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 que RtlInsertElementGenericTableAvl ne peut pas insérer la nouvelle entrée (par exemple, parce que l’objet AllocateRoutine échoue), RtlInsertElementGenericTableAvl retourne NULL.
Remarques
Pour insérer une entrée, RtlInsertElementGenericTableAvl appelle CompareRoutine et AllocateRoutine qui ont été inscrits lorsque la table générique a été initialisée par RtlInitializeGenericTableAvl. Après avoir inséré la nouvelle entrée, RtlInsertElementGenericTableAvl rééquilibre l’arborescence de liens AVL.
Lorsqu’une nouvelle entrée est insérée dans la table, ses données sont copiées à partir de Buffer dans la nouvelle entrée. Par conséquent, le pointeur retourné par RtlInsertElementGenericTableAvl n’est jamais égal à Buffer.
Si le CompareRoutine de l’appelant retourne GenericEqual, les données dans Buffer sont supposées dupliquer les données d’une entrée existante dans la table générique. Dans ce cas, RtlInsertElementGenericTableAvl n’ajoute pas la nouvelle entrée (et n’appelle donc pas l’AllocationRoutine), 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, RtlInsertElementGenericTableAvl retourne un pointeur vers les données de l’entrée existante et définit NewElement sur FALSE.
S’il n’y a pas encore d’entrée correspondante dans la table, la routine RtlInsertElementGenericTableAvl alloue suffisamment d’espace pour les données utilisateur de la nouvelle entrée (BufferSize) plus les liens associés à la nouvelle entrée. Par conséquent, le nombre total d’octets sera d’au moins taille bufferSizeof + (RTL_BALANCED_LINKS). L’appelant ne doit pas utiliser les premiers octets de taille(RTL_BALANCED_LINKS) de la mémoire allouée par l’allocationRoutine.
Appelants du Rtl.. Les routines GenericTableAvl sont chargées de synchroniser exclusivement 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 lecture pour implémenter des tables génériques, mais la routine RtlInsertElementGenericTableAvl 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. Par exemple, utilisez la routine RtlInsertElementGenericTableAvl au lieu de RtlInsertElementGenericTable. Dans l’appel à RtlInsertElementGenericTableAvl, l’appelant doit passer une structure de table RTL_AVL_TABLE plutôt que RTL_GENERIC_TABLE.
Les appelants de RtlInsertElementGenericTableAvl doivent être en cours d’exécution sur IRQL < DISPATCH_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.
- CompareRoutine ou AllocateRoutine fourni par l’appelant contient du code paginable.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows XP. |
| Plateforme cible | Universal |
| En-tête | ntddk.h (inclure Ntddk.h, Ntifs.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (voir la section Remarques) |