RtlInsertElementGenericTableAvl-Funktion (ntddk.h)
Die RtlInsertElementGenericTableAvl-Routine fügt einer generischen Tabelle einen neuen Eintrag hinzu.
Syntax
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parameter
[in] Table
Zeiger auf eine generische Adelson-Velsky/Landis(AVL)-Tabelle (RTL_AVL_TABLE), die durch einen Aufruf von RtlInitializeGenericTableAvl initialisiert wurde.
[in] Buffer
Ein vom Aufrufer zugewiesener Puffer, der die Benutzerdaten enthält, die in das neue Element kopiert werden sollen. Weitere Informationen finden Sie unter RtlInitializeGenericTableAvl.
[in] BufferSize
Größe der Daten in Bytes im Puffer.
[out, optional] NewElement
Bei der Ausgabe bedeutet der Wert TRUE , dass das Einfügen des neuen Elements in die generische Tabelle erfolgreich war. Der Wert FALSE bedeutet, dass beim Einfügen ein Fehler aufgetreten ist.
Rückgabewert
RtlInsertElementGenericTableAvl gibt einen Zeiger auf die Benutzerdaten für den neu eingefügten Eintrag oder die Benutzerdaten für einen übereinstimmenden Eintrag zurück, der sich bereits in der generischen Tabelle befindet. Wenn kein übereinstimmenden Eintrag gefunden wird, aber RtlInsertElementGenericTableAvl den neuen Eintrag nicht einfügen kann (z. B. weil die AllocateRoutine fehlschlägt), gibt RtlInsertElementGenericTableAvlNULL zurück.
Hinweise
Um einen Eintrag einzufügen, ruft RtlInsertElementGenericTableAvl die CompareRoutine und AllocateRoutine auf, die registriert wurden, als die generische Tabelle von RtlInitializeGenericTableAvl initialisiert wurde. Nach dem Einfügen des neuen Eintrags glich RtlInsertElementGenericTableAvl die AVL-Linkstruktur neu aus.
Wenn ein neuer Eintrag in die Tabelle eingefügt wird, werden die zugehörigen Daten aus Buffer in den neuen Eintrag kopiert. Daher ist der von RtlInsertElementGenericTableAvl zurückgegebene Zeiger niemals gleich Buffer.
Wenn compareRoutine des Aufrufers GenericEqual zurückgibt, wird davon ausgegangen, dass die Daten bei Buffer die Daten für einen vorhandenen Eintrag in der generischen Tabelle duplizieren. In diesem Fall fügt RtlInsertElementGenericTableAvl den neuen Eintrag nicht hinzu (und ruft daher die AllocateRoutine nicht auf), da eine generische Tabelle keine doppelten Einträge enthalten kann.
Wenn bereits ein übereinstimmenden Eintrag in der generischen Tabelle vorhanden ist, gibt RtlInsertElementGenericTableAvl einen Zeiger auf die Daten des vorhandenen Eintrags zurück und legt NewElement auf FALSE fest.
Wenn es bereits keinen übereinstimmenden Eintrag in der Tabelle gibt, belegt die RtlInsertElementGenericTableAvl-Routine ausreichend Speicherplatz für die Benutzerdaten des neuen Eintrags (BufferSize) plus die dem neuen Eintrag zugeordneten Links. Daher beträgt die Gesamtzahl der Bytes mindestens BufferSize + sizeof(RTL_BALANCED_LINKS). Der Aufrufer sollte nicht die ersten sizeof(RTL_BALANCED_LINKS)-Bytes des Arbeitsspeichers verwenden, den die AllocateRoutinezuordnet.
Anrufer der Rtl.. GenericTableAvl-Routinen sind für die ausschließliche Synchronisierung des Zugriffs auf die generische Tabelle verantwortlich. Ein exklusiver schneller Mutex ist der effizienteste Synchronisierungsmechanismus, der für diesen Zweck verwendet werden kann.
Standardmäßig verwendet das Betriebssystem splay-Strukturen, um generische Tabellen zu implementieren, aber die RtlInsertElementGenericTableAvl-Routine funktioniert nur mit Adelson-Velsky/Landis-Strukturen (AVL). Um die generischen Tabellenroutinen so zu konfigurieren, dass sie AVL-Strukturen anstelle von Splaystrukturen in Ihrem Treiber verwenden, fügen Sie die folgende define-Anweisung in eine allgemeine Headerdatei ein, bevor Sie Ntddk.h einschließen:
#define RTL_USE_AVL_TABLES 0
Wenn RTL_USE_AVL_TABLES nicht definiert ist, müssen Sie die AVL-Form der generischen Tabellenroutinen verwenden. Verwenden Sie beispielsweise die RtlInsertElementGenericTableAvl-Routine anstelle von RtlInsertElementGenericTable. Im Aufruf von RtlInsertElementGenericTableAvl muss der Aufrufer anstelle von RTL_GENERIC_TABLE eine RTL_AVL_TABLE Tabellenstruktur übergeben.
Aufrufer von RtlInsertElementGenericTableAvl müssen im IRQL-DISPATCH_LEVEL < ausgeführt werden, wenn eine der folgenden Bedingungen erfüllt ist:
- Der vom Aufrufer zugeordnete Arbeitsspeicher bei Table oder buffer kann ausgelagert werden.
- Die vom Aufrufer bereitgestellte CompareRoutine oder AllocateRoutine enthält ausgelagerten Code.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows XP. |
| Zielplattform | Universell |
| Header | ntddk.h (include Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (siehe Abschnitt "Hinweise") |