RtlInitializeGenericTable-Funktion (ntddk.h)
Die RtlInitializeGenericTable-Routine initialisiert eine generische Tabelle.
Syntax
NTSYSAPI VOID RtlInitializeGenericTable(
[out] PRTL_GENERIC_TABLE Table,
[in] PRTL_GENERIC_COMPARE_ROUTINE CompareRoutine,
[in] PRTL_GENERIC_ALLOCATE_ROUTINE AllocateRoutine,
[in] PRTL_GENERIC_FREE_ROUTINE FreeRoutine,
[in, optional] PVOID TableContext
);
Parameter
[out] Table
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der mindestens sizeof(RTL_GENERIC_TABLE)-Bytes sein muss, um die initialisierte generische Tabellenstruktur zu enthalten.
[in] CompareRoutine
Ein Einstiegspunkt einer Vergleichsrückrufroutine, die wie folgt deklariert wird:
RTL_GENERIC_COMPARE_RESULTS
(*PRTL_GENERIC_COMPARE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in PVOID FirstStruct,
__in PVOID SecondStruct
);
Die CompareRoutine-Parameter sind wie folgt:
Tabelle (CompareRoutine)
Ein Zeiger auf die generische Tabelle.
FirstStruct
Ein Zeiger auf das erste zu vergleichende Element.
SecondStruct
Ein Zeiger auf das zweite Element, das verglichen werden soll.
Die CompareRoutine muss die Reihenfolge aller Elemente in der generischen Tabelle genau nachverfolgen, damit sie ein bestimmtes Element identifizieren kann. Die vom Aufrufer definierte Struktur für Elementdaten enthält in der Regel ein Element, dessen Wert eindeutig ist und als Sortierschlüssel verwendet werden kann. Alle Rtl... GenericTable-Routinen , die die CompareRoutine aufrufen, verwenden einen Pufferzeiger als Parameter, der wiederum an die CompareRoutine übergeben wird. Der Puffer enthält einen vom Aufrufer bereitgestellten Schlüsselwert, der von der CompareRoutine mit dem Schlüssel des Elements abgeglichen werden soll, nach dem gesucht wird.
Bei zwei solchen Schlüsselwerten gibt compareRoutineGenericLessThan, GenericGreaterThan oder GenericEqual zurück.
[in] AllocateRoutine
Ein Einstiegspunkt einer Zuordnungsrückrufroutine, die wie folgt deklariert wird:
PVOID
(*PRTL_GENERIC_ALLOCATE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in CLONG ByteSize
);
Die AllocateRoutine-Parameter sind wie folgt:
Tabelle (AllocateRoutine)
Ein Zeiger auf die generische Tabelle.
ByteSize
Die Anzahl der zu belegenden Bytes.
Für jedes neue Element wird die AllocateRoutine aufgerufen, um Arbeitsspeicher für vom Aufrufer bereitgestellte Daten zuzuweisen, sowie etwas zusätzlichen Arbeitsspeicher für die Verwendung durch die Rtl... GenericTable-Routinen . Beachten Sie, dass die vom Aufrufer bereitgestellten Routinen aufgrund dieses "zusätzlichen Arbeitsspeichers" nicht auf die ersten Bytes (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) eines Elements in der generischen Tabelle zugreifen dürfen.
[in] FreeRoutine
Ein Einstiegspunkt einer Deallocation-Rückrufroutine, die wie folgt deklariert wird:
VOID
(*PRTL_GENERIC_FREE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in PVOID Buffer
);
Die FreeRoutine-Parameter sind wie folgt:
Tabelle (FreeRoutine)
Ein Zeiger auf die generische Tabelle.
Buffer
Ein Zeiger auf das Element, das gelöscht wird.
Rtl... GenericTable-Routinen rufen die FreeRoutine auf, um die Zuordnung von Arbeitsspeicher für Elemente zu beheben, die aus der generischen Tabelle gelöscht werden sollen. Die FreeRoutine ist das Gegenteil von AllocateRoutine.
[in, optional] TableContext
Ein optionaler Zeiger auf einen vom Aufrufer bereitgestellten Kontext für die generische Tabelle. Dieser Parameter kann NULL sein.
Rückgabewert
Keine
Bemerkungen
Dateisysteme rufen RtlInitializeGenericTable auf, um eine generische Tabelle zum Speichern dateisystemspezifischer Daten zu initialisieren, z. B. Name-Nachschlageinformationen für aktuell geöffnete Dateien. Die Sortierreihenfolge, Die Struktur und der Inhalt der Elemente werden vom Aufrufer definiert.
Dateisysteme müssen RtlInitializeGenericTable aufrufen, um die generische Tabelle zu initialisieren, bevor sie andere Rtl... GenericTable-Routinen für die neue generische Tabelle. Die initialisierte generische Tabellenstruktur sollte als undurchsichtig betrachtet werden.
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.
Die vom Aufrufer bereitgestellte CompareRoutine wird vor der AllocateRoutine aufgerufen, um eine geeignete Position zu finden, an der ein neues Element eingefügt werden soll. Die CompareRoutine wird auch vor der FreeRoutine aufgerufen, um nach einem zu löschenden Element zu suchen.
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 Sie AVL-Tabellen verwenden möchten und RTL_USE_AVL_TABLES nicht definiert ist, müssen Sie die AVL-Form der generischen Tabellenroutinen verwenden. Verwenden Sie beispielsweise die RtlInitializeGenericTableAvl-Routine anstelle von RtlInitializeGenericTable. RtlInitializeGenericTableAvl gibt eine initialisierte RTL_AVL_TABLE Tabellenstruktur im Puffer zurück, auf die der Table-Parameter verweist. Beim Aufruf von RtlInitializeGenericTableAvl muss der Aufrufer eine PRTL_AVL_COMPARE_ROUTINE typisierte Vergleichsrückrufroutine, eine PRTL_AVL_ALLOCATE_ROUTINE typisierte Zuordnungsrückrufroutine und eine PRTL_AVL_FREE_ROUTINE typisierte Deallocation-Rückrufroutine anstelle der ähnlichen PRTL_GENERIC_Xxx-typisierten Routinen übergeben.
Aufrufer von RtlInitializeGenericTable müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Beachten Sie, dass, wenn Rtl... GenericTable-Routinen sollen im IRQL-DISPATCH_LEVEL verwendet werden. CompareRoutine, AllocateRoutine und FreeRoutine müssen alle nicht ausstellbaren Code sein, und die AllocateRoutine sollte Arbeitsspeicher aus einem nicht auslagerten Pool zuweisen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (siehe Abschnitt Hinweise) |