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 Größe von(RTL_GENERIC_TABLE) Bytes in der Größe aufweisen muss, um die initialisierte generische Tabellenstruktur zu enthalten.
[in] CompareRoutine
Ein Einstiegspunkt einer Vergleichsrückrufroutine, deklariert wie folgt:
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 zu vergleichende Element.
Die CompareRoutine- muss die Sortierung aller Elemente in der generischen Tabelle streng nachverfolgen, damit sie ein bestimmtes Element identifizieren kann. Die aufruferdefinierte 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, einen Pufferzeiger als Parameter verwenden, der wiederum an die CompareRoutineübergeben wird. Der Puffer enthält einen vom Aufrufer bereitgestellten Schlüsselwert, der vom CompareRoutine- mit dem Schlüssel des gesuchten Elements abgeglichen werden soll.
Bei zwei solchen Schlüsselwerten gibt die CompareRoutineGenericLessThan, GenericGreaterThanoder GenericEqualzurü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 parameter AllocateRoutine sind wie folgt:
Tabelle (AllocateRoutine)
Ein Zeiger auf die generische Tabelle.
ByteSize
Die Anzahl der zuzuordnenden Bytes.
Für jedes neue Element wird die AllocateRoutine aufgerufen, um Speicher für vom Anrufer bereitgestellte Daten sowie zusätzlichen Speicher für die Verwendung durch den Rtl zuzuweisen... GenericTable Routinen. Beachten Sie, dass aufruferbasierte Routinen aufgrund dieser "zusätzlichen Arbeitsspeicher" nicht auf die erste (Größe von(RTL_SPLAY_LINKS) + Größe von(LIST_ENTRY)))-Bytes eines elements in der generischen Tabelle zugreifen dürfen.
[in] FreeRoutine
Ein Einstiegspunkt einer Deallocation-Rückrufroutine, deklariert wie folgt:
VOID
(*PRTL_GENERIC_FREE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in PVOID Buffer
);
Die parameter FreeRoutine sind wie folgt:
Tabelle (FreeRoutine)
Ein Zeiger auf die generische Tabelle.
Puffer
Ein Zeiger auf das Element, das gelöscht wird.
Rtl... GenericTable- Routinen rufen die FreeRoutine- auf, um Speicher für Elemente zu behandeln, die aus der generischen Tabelle gelöscht werden sollen. Die FreeRoutine- ist das Gegenteil der 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
Nichts
Bemerkungen
Dateisysteme rufen RtlInitializeGenericTable- auf, um eine generische Tabelle zum Speichern systemspezifischer Daten zu initialisieren, z. B. Nachschlageinformationen für aktuell geöffnete Dateien. Die Sortierreihenfolge, Struktur und Der Inhalt der Elemente werden aufruferdefiniert.
Dateisysteme müssen RtlInitializeGenericTable- aufrufen, um die generische Tabelle zu initialisieren, bevor sie andere Rtl verwenden... GenericTable Routinen in der neuen generischen Tabelle. Die initialisierte generische Tabellenstruktur sollte als undurchsichtig betrachtet werden.
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.
Die vom Aufrufer bereitgestellte CompareRoutine- wird aufgerufen, bevor die AllocateRoutine-, um einen geeigneten Speicherort zu finden, an dem ein neues Element eingefügt werden soll. Die CompareRoutine wird auch vor dem FreeRoutine- aufgerufen, um ein zu löschenes Element zu suchen.
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 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 RtlInitializeGenericTable. RtlInitializeGenericTableAvl gibt eine initialisierte RTL_AVL_TABLE Tabellenstruktur im Puffer zurück, auf die der Table Parameter verweist. Im Aufruf von RtlInitializeGenericTableAvlmuss der Aufrufer eine PRTL_AVL_COMPARE_ROUTINE typisierten Vergleichsrückrufroutine, eine PRTL_AVL_ALLOCATE_ROUTINE typisierten Zuordnungsrückrufroutine und eine PRTL_AVL_FREE_ROUTINE-typierte Deallocation-Rückrufroutine anstelle der ähnlichen PRTL_GENERIC_Xxx--typed-Routinen übergeben.
Anrufer von RtlInitializeGenericTable- müssen bei IRQL <= DISPATCH_LEVEL ausgeführt werden. Beachten Sie, dass, wenn Rtl... GenericTable- Routinen sind für IRQL-DISPATCH_LEVEL, die CompareRoutine, AllocateRoutineund FreeRoutine- müssen alle nicht ausspagebaren Code sein, und die AllocateRoutine- sollte Speicher aus nicht seitenseitigem Pool zuweisen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | IRQL-<= DISPATCH_LEVEL (siehe Abschnitt "Hinweise") |