RtlInsertElementGenericTable-Funktion (ntddk.h)
Die RtlInsertElementGenericTable-Routine fügt einer generischen Tabelle ein neues Element hinzu.
Syntax
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parameter
[in] Table
Zeiger auf die generische Tabelle (RTL_GENERIC_TABLE). Die Tabelle muss durch Aufrufen von RtlInitializeGenericTable initialisiert worden sein.
[in] Buffer
Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der Daten enthält, die in das neue Element kopiert werden sollen. Weitere Informationen finden Sie in der Beschreibung von RtlInitializeGenericTable.
[in] BufferSize
Anzahl der Bytes, die beim Einfügen des neuen Elements für vom Aufrufer bereitgestellte Daten zugeordnet werden sollen.
[out, optional] NewElement
Zeiger auf eine Variable, die TRUE empfängt, wenn ein neues Element mit den Daten von Buffer in die generische Tabelle eingefügt wurde; oder FALSE , wenn das neue Element nicht eingefügt wurde.
Rückgabewert
RtlInsertElementGenericTable gibt einen Zeiger auf die zugeordneten Daten des neu eingefügten Elements zurück oder gibt einen Zeiger auf die Daten des vorhandenen Elements zurück, wenn bereits ein übereinstimmende Element in der generischen Tabelle vorhanden ist. Wenn kein übereinstimmende Element gefunden wird, aber das neue Element nicht eingefügt werden kann (z. B. weil die AllocateRoutine fehlschlägt), gibt RtlInsertElementGenericTableNULL zurück.
Hinweise
Zum Einfügen eines Elements ruft RtlInsertElementGenericTable die CompareRoutine und AllocateRoutine auf, die registriert wurden, als die generische Tabelle von RtlInitializeGenericTable initialisiert wurde. Nach dem Einfügen des neuen Elements balanciert RtlInsertElementGenericTable die Splay-Linkstruktur neu aus.
Wenn ein neues Element in die Tabelle eingefügt wird, werden dessen Daten aus Buffer in das neue Element kopiert. Daher ist der von RtlInsertElementGenericTable zurückgegebene Zeiger nie gleich Puffer.
Wenn compareRoutine des Aufrufers GenericEqual zurückgibt, wird davon ausgegangen, dass die Daten bei Buffer die Daten für ein vorhandenes Element in der generischen Tabelle duplizieren. In diesem Fall fügt RtlInsertElementGenericTable das neue Element nicht hinzu (und ruft daher nicht die AllocateRoutine auf), da eine generische Tabelle keine doppelten Elemente aufweisen kann.
Wenn in der generischen Tabelle bereits ein übereinstimmende Element vorhanden ist, gibt RtlInsertElementGenericTable einen Zeiger auf die Daten des vorhandenen Elements zurück und legt NewElement auf FALSE fest.
Anrufer der Rtl.. GenericTable-Routinen sind ausschließlich für die Synchronisierung des Zugriffs auf die generische Tabelle verantwortlich. Ein exklusiver schneller Mutex ist der effizienteste Synchronisierungsmechanismus für diesen Zweck.
Standardmäßig verwendet das Betriebssystem Splay-Strukturen, um generische Tabellen zu implementieren. Unter bestimmten Umständen wird die Struktur durch Vorgänge in einer Splay-Struktur tief und schmal und kann sogar in eine gerade Linie umgewandelt werden. Sehr tiefe Bäume beeinträchtigen die Leistung von Suchvorgängen. Mithilfe von Adelson-Velsky/Landis-Bäumen (AVL) können Sie eine ausgewogenere, flachere Strukturimplementierung generischer Tabellen sicherstellen. Wenn Sie die generischen Tabellenroutinen so konfigurieren möchten, dass sie AVL-Strukturen anstelle von splay-Strukturen 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 eine RTL_AVL_TABLE Tabellenstruktur übergeben, anstatt RTL_GENERIC_TABLE.
Aufrufer von RtlInsertElementGenericTable müssen bei IRQL < DISPATCH_LEVEL ausgeführt werden, wenn eine der folgenden Bedingungen erfüllt ist:
- Der vom Aufrufer zugewiesene Arbeitsspeicher bei Table oder bei Buffer kann ausgelagert werden.
- Die vom Aufrufer bereitgestellte CompareRoutine oder AllocateRoutine enthält ausserwählbaren Code.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | ntddk.h (include Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (siehe Abschnitt Hinweise) |