Fonction RtlInsertElementGenericTableFullAvl (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 (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é.

[in] NodeOrParent

Résultat de recherche d’un appel précédent à RtlLookupElementGenericTableFullAvl. Cette valeur indique à la routine RtlInsertElementGenericTableFullAvl si l’arborescence est actuellement vide, ou s’il 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 NodeOrParentn’a pas été modifié.

TableFoundNode

La routine RtlInsertElementGenericTableFullAvl a trouvé une entrée de table dont la clé correspond aux données dans Buffer. NodeOrParent contient un pointeur vers l’entrée correspondante.

TableInsertAsLeft

La routine RtlInsertElementGenericTableFullAvl n’a pas trouvé d’entrée de table dont la clé correspond aux données dans Buffer. Si l’entrée recherchée par RtlInsertElementGenericTableFullAvl se trouve dans la table, il s’agit de l’enfant gauche de l’entrée vers laquelle nodeOrParent pointe.

TableInsertAsRight

La routine RtlInsertElementGenericTableFullAvl n’a pas trouvé d’entrée de table dont la clé correspond aux données dans Buffer. Si l’entrée recherchée par RtlInsertElementGenericTableFullAvl se trouve dans la table, il s’agit de l’enfant approprié de l’entrée vers 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 que la routine RtlInsertElementGenericTableFullAvl recherchait.

Valeur retournée

RtlInsertElementGenericTableFullAvl retourne un pointeur vers les données utilisateur pour 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 RtlInsertElementGenericTableFullAvl ne peut pas insérer la nouvelle entrée (par exemple, parce que l’objet AllocateRoutine échoue), RtlInsertElementGenericTableFullAvl retourne NULL.

Remarques

Pour insérer une entrée, RtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl 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. Ainsi, le pointeur retourné par RtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl n’ajoute pas la nouvelle entrée (et n’appelle donc pas l’objet 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 de l’entrée existante et définit NewElement sur FALSE.

S’il n’existe pas encore d’entrée correspondante dans la table, la routine RtlInsertElementGenericTableFullAvl 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 + (BALANCED_LINKS). L’appelant ne doit pas utiliser les premiers octets sizeof(BALANCED_LINKS) de la mémoire allouée par l’objet AllocateRoutine.

Appelants duRtl.. 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 RtlInsertElementGenericTableFullAvl 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 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 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

Voir aussi

RtlDeleteElementGenericTable

RtlInitializeGenericTable