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
Zeigen Sie 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
Die Anzahl der Bytes, die für vom Anrufer bereitgestellte Daten zugewiesen werden sollen, wenn das neue Element eingefügt wird.
[out, optional] NewElement
Zeiger auf eine Variable, die TRUE empfängt, wenn ein neues Element mit den Daten bei Buffer in die generische Tabelle eingefügt wurde; oder FALSE, wenn das neue Element nicht eingefügt wurde.
Rückgabewert
RtlInsertElementGenericTable einen Zeiger auf die verknüpften 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.
Bemerkungen
Um ein Element einzufügen, ruft RtlInsertElementGenericTable die CompareRoutine und AllocateRoutine auf, die beim Initialisieren der generischen Tabelle durch RtlInitializeGenericTableregistriert wurden. Nach dem Einfügen des neuen Elements RtlInsertElementGenericTable die Verknüpfungsstruktur für die Wiedergabe neu ausbalanciert.
Wenn ein neues Element in die Tabelle eingefügt wird, werden die Daten aus Buffer in das neue Element kopiert. Daher entspricht der von RtlInsertElementGenericTable zurückgegebene Zeiger niemals Buffer-.
Wenn die CompareRoutine- des Aufrufers GenericEqual-zurückgibt, werden die Daten bei Buffer angenommen, um die Daten für ein vorhandenes Element in der generischen Tabelle zu 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 übereinstimmenes 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 für die ausschließliche 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 werden Vorgänge in einem Spielbaum den Baum tief und schmal machen und ihn sogar in eine gerade Linie verwandeln. Sehr tiefe Bäume beeinträchtigen die Leistung von Suchvorgängen. Sie können eine ausgewogenere, flachere Strukturimplementierung generischer Tabellen sicherstellen, indem Sie Adelson-Velsky/Landis (AVL)-Strukturen verwenden. Wenn Sie die generischen Tabellenroutinen so konfigurieren möchten, dass AVL-Strukturen anstelle von Splay-Strukturen in Ihrem Treiber verwendet werden, fügen Sie die folgende Define-Anweisung in eine allgemeine Headerdatei ein, bevor Sie Ntddk.heinschließ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 RtlInsertElementGenericTable. Im Aufruf von RtlInsertElementGenericTableAvlmuss der Aufrufer eine RTL_AVL_TABLE Tabellenstruktur statt RTL_GENERIC_TABLEübergeben.
Anrufer von RtlInsertElementGenericTable müssen bei IRQL-< DISPATCH_LEVEL ausgeführt werden, wenn eine der folgenden Bedingungen gilt:
- Der vom Aufrufer zugewiesene Speicher in Table oder bei Buffer kann ausgelagert werden.
- Der vom Aufrufer bereitgestellte CompareRoutine oder AllocateRoutine- enthält ausgelagerten Code.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | ntddk.h (enthalten Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | < DISPATCH_LEVEL (siehe Abschnitt "Hinweise") |