RtlInsertElementGenericTableAvl, fonction (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 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é.
Valeur de retour
RtlInsertElementGenericTableAvl 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 RtlInsertElementGenericTableAvl ne peut pas insérer la nouvelle entrée (par exemple, car l'AllocateRoutine échoue), RtlInsertElementGenericTableAvl retourne NULL.
Remarques
Pour insérer une entrée, RtlInsertElementGenericTableAvl appelle le CompareRoutine et AllocateRoutine inscrits lors de l’initialisation de la table générique par RtlInitializeGenericTableAvl. Après avoir inséré la nouvelle entrée, RtlInsertElementGenericTableAvl rééquilibrer 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 RtlInsertElementGenericTableAvl 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, RtlInsertElementGenericTableAvl 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, RtlInsertElementGenericTableAvl retourne un pointeur vers les données de l’entrée existante et définit NewElement sur FALSE.
S’il n’existe pas d’entrée correspondante dans la table déjà,RtlInsertElementGenericTableAvl 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(RTL_BALANCED_LINKS). L’appelant ne doit pas utiliser la première taille (RTL_BALANCED_LINKS) octets de la mémoire allouée par le AllocateRoutine.
Appelants du Rtl.. 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 RtlInsertElementGenericTableAvl 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 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 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 à partir de Windows XP. |
| 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) |