Fonction RtlInsertElementGenericTable (ntddk.h)
La routine RtlInsertElementGenericTable ajoute un nouvel élément à une table générique.
Syntaxe
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Paramètres
[in] Table
Pointeur vers la table générique (RTL_GENERIC_TABLE). La table doit avoir été initialisée en appelant RtlInitializeGenericTable.
[in] Buffer
Pointeur vers une mémoire tampon allouée à l’appelant contenant des données à copier dans le nouvel élément. Pour plus d’informations, consultez la description de RtlInitializeGenericTable.
[in] BufferSize
Nombre d’octets à allouer pour les données fournies par l’appelant lors de l’insertion du nouvel élément.
[out, optional] NewElement
Pointeur vers une variable qui reçoit TRUE si un nouvel élément avec les données de la mémoire tampon a été inséré dans la table générique ; ou FALSE si le nouvel élément n’a pas été inséré.
Valeur retournée
RtlInsertElementGenericTable retourne un pointeur vers les données associées de l’élément nouvellement inséré, ou renvoie un pointeur vers les données de l’élément existant si un élément correspondant existe déjà dans la table générique. Si aucun élément correspondant n’est trouvé, mais que le nouvel élément ne peut pas être inséré (par exemple, parce que l’objet AllocateRoutine échoue), RtlInsertElementGenericTable retourne NULL.
Remarques
Pour insérer un élément, RtlInsertElementGenericTable appelle CompareRoutine et AllocateRoutine qui ont été inscrits lorsque la table générique a été initialisée par RtlInitializeGenericTable. Après avoir inséré le nouvel élément, RtlInsertElementGenericTable rééquilibre l’arborescence de liens de lecture.
Lorsqu’un nouvel élément est inséré dans la table, ses données sont copiées à partir de Buffer dans le nouvel élément. Par conséquent, le pointeur retourné par RtlInsertElementGenericTable n’est jamais égal à Buffer.
Si le CompareRoutine de l’appelant retourne GenericEqual, les données de la mémoire tampon sont supposées dupliquer les données d’un élément existant dans la table générique. Dans ce cas, RtlInsertElementGenericTable n’ajoute pas le nouvel élément (et n’appelle donc pas l’objet AllocateRoutine), car une table générique ne peut pas avoir d’éléments en double.
Si un élément correspondant existe déjà dans la table générique, RtlInsertElementGenericTable retourne un pointeur vers les données de l’élément existant et définit NewElement sur FALSE.
Appelants du Rtl.. Les routines GenericTable 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 lecture pour implémenter des tables génériques. Dans certaines circonstances, les opérations sur un arbre de jeu rendent l’arbre profond et étroit et peut même le transformer en une ligne droite. Les arbres très profonds dégradent les performances des recherches. Vous pouvez garantir une implémentation d’arborescence plus équilibrée et moins profonde des tables génériques à l’aide des arborescences Adelson-Velsky/Landis (AVL). Si vous souhaitez configurer les routines de table génériques pour 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 RtlInsertElementGenericTable 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 |
|---|---|
| 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) |