RtlInitializeGenericTableAvl-Funktion (ntddk.h)

Artikel
03/08/2023

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

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 zugeordneten Puffer, der mindestens sizeof(RTL_AVL_TABLE) Bytes groß 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 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... GenericTableAvl-Routinen , die compareRoutine aufrufen, verwenden einen Pufferzeiger als Parameter, der wiederum an compareRoutine übergeben wird. Der Puffer enthält einen vom Aufrufer bereitgestellten Schlüsselwert, der von 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, deklariert wie folgt:

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_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 sowie einen zusätzlichen Arbeitsspeicher für die Verwendung durch die Rtl...-Klasse zuzuweisen . GenericTableAvl-Routinen . Beachten Sie, dass aufgrund dieses "zusätzlichen Arbeitsspeichers" vom Aufrufer bereitgestellte Routinen nicht auf die ersten sizeof(RTL_BALANCED_LINKS) Bytes eines Elements in der generischen Tabelle zugreifen dürfen.

[in] FreeRoutine

Ein Einstiegspunkt einer Rückrufroutine für die Aufhebung der Zuordnung, deklariert wie folgt:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_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... GenericTableAvl-Routinen rufen die FreeRoutine auf, um die Zuordnung von Speicher für Elemente aufzugeben, 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 RtlInitializeGenericTableAvl auf, um eine generische Tabelle zum Speichern von dateisystemspezifischen Daten zu initialisieren, z. B. Namenssuchinformationen für aktuell geöffnete Dateien. Die Sortierreihenfolge, die Struktur und der Inhalt der Elemente sind aufruferdefiniert.

Dateisysteme müssen RtlInitializeGenericTableAvl aufrufen, um die generische Tabelle zu initialisieren, bevor sie andere Rtl... GenericTableAvl-Routinen für die neue generische Tabelle. Die initialisierte generische Tabellenstruktur sollte als undurchsichtig angesehen 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, der für diesen Zweck verwendet werden kann.

Die vom Aufrufer bereitgestellte CompareRoutine wird vor der AllocateRoutine aufgerufen, um einen geeigneten Speicherort zu finden, an dem ein neues Element eingefügt werden soll. Die CompareRoutine wird auch vor der FreeRoutine aufgerufen, um nach einem element zu suchen, das gelöscht werden soll.

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 gewünscht sind und RTL_USE_AVL_TABLES vor dem Einschließen von "Ntddk.h" nicht definiert ist.

Wenn Sie die generischen Tabellenroutinen konfigurieren möchten, rtl... Um AVL-Strukturen anstelle von Splaystrukturen in Ihrem Treiber zu 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`

Aufrufer von RtlInitializeGenericTableAvl müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Beachten Sie, dass, wenn Rtl... GenericTableAvl-Routinen werden im IRQL-DISPATCH_LEVEL verwendet, compareRoutine, AllocateRoutine und FreeRoutine müssen alle nicht ausserstellbaren 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")