RtlInitializeGenericTableAvl-Funktion (ntddk.h)

Artikel
02/07/2025

Die RtlInitializeGenericTableAvl Routine initialisiert eine generische Tabelle mit Adelson-Velsky/Landis (AVL)-Strukturen.

Syntax

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                     TableContext
);

Parameter

[out] Table

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der mindestens Größe von(RTL_AVL_TABLE) Bytes in größe sein muss, um die initialisierte generische Tabellenstruktur zu enthalten.

[in] CompareRoutine

Ein Einstiegspunkt einer Vergleichsrückrufroutine, deklariert wie folgt:

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_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... GenericTableAvl 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_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_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... GenericTableAvl Routinen. Beachten Sie, dass aufruferbasierte Routinen aufgrund dieser "zusätzlichen Arbeitsspeicher" nicht auf die erste Größe von(RTL_BALANCED_LINKS) Bytes eines Elements in der generischen Tabelle zugreifen dürfen.

[in] FreeRoutine

Ein Einstiegspunkt einer Deallocation-Rückrufroutine, deklariert wie folgt:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_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... GenericTableAvl- Routinen rufen die FreeRoutine- auf, um speicheraufzuweisen, damit Elemente aus der generischen Tabelle gelöscht werden. 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 RtlInitializeGenericTableAvl 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 RtlInitializeGenericTableAvl aufrufen, um die generische Tabelle zu initialisieren, bevor sie andere Rtl verwenden... GenericTableAvl Routinen für die neue generische Tabelle. Die initialisierte generische Tabellenstruktur sollte als undurchsichtig betrachtet werden.

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 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.

Die RtlInitializeGenericTableAvl Routine weist explizit eine generische Tabelle zu, die AVL-Strukturen verwendet. Verwendung dieser Routine und der anderen Rtl... GenericTableAvl- Routinen sind erforderlich, wenn AVL-strukturbasierte Tabellen erwünscht sind und RTL_USE_AVL_TABLES nicht definiert werden, bevor Ntddk.heingeschlossen wird.

Wenn Sie die generischen Tabellenroutinen konfigurieren möchten, Rtl... GenericTable, um AVL-Strukturen anstelle von Splay-Strukturen in Ihrem Treiber zu verwenden, fügen Sie die folgende Define-Anweisung in eine allgemeine Headerdatei ein, bevor Ntddk.heingeschlossen wird:

`#define RTL_USE_AVL_TABLES 0`

Anrufer von RtlInitializeGenericTableAvl müssen bei IRQL-<= DISPATCH_LEVEL ausgeführt werden. Beachten Sie, dass, wenn Rtl... GenericTableAvl- Routinen sind für IRQL-DISPATCH_LEVEL, die CompareRoutine-, "AllocateRoutine" und FreeRoutine- müssen alle nicht seitenseitigen Code sein, und die "AllocateRoutine"- sollten 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")