Funzione RtlInitializeGenericTableAvl (ntddk.h)

Articolo
02/07/2025

La routine RtlInitializeGenericTableAvl inizializza una tabella generica usando alberi Adelson-Velsky/Landis (AVL).

Sintassi

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
);

Parametri

[out] Table

Puntatore a un buffer allocato dal chiamante, che deve essere almeno sizeof(RTL_AVL_TABLE) byte per contenere la struttura di tabella generica inizializzata.

[in] CompareRoutine

Punto di ingresso di una routine di callback di confronto, dichiarato come segue:

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    );

I parametri di CompareRoutine sono i seguenti:

Tabella (CompareRoutine)

Puntatore alla tabella generica.

FirstStruct

Puntatore al primo elemento da confrontare.

SecondStruct

Puntatore al secondo elemento da confrontare.

Il CompareRoutine deve tenere traccia rigorosa dell'ordinamento di tutti gli elementi della tabella generica in modo che possa identificare qualsiasi elemento specifico. La struttura definita dal chiamante per i dati degli elementi include in genere un membro il cui valore è univoco e può essere usato come chiave di ordinamento. Tutti Rtl... GenericTableAvl routine che chiamano la CompareRoutine accettano un puntatore del buffer come parametro, che viene passato a sua volta alla CompareRoutine. Il buffer contiene un valore di chiave fornito dal chiamante che deve corrispondere al CompareRoutine alla chiave dell'elemento cercato.

Dato due valori di chiave di questo tipo, il CompareRoutine restituisce GenericLessThan, GenericGreaterThano GenericEqual.

[in] AllocateRoutine

Un punto di ingresso di una routine di callback di allocazione, dichiarato come segue:

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in CLONG  ByteSize
    );

I parametri AllocateRoutine sono i seguenti:

Tabella (AllocateRoutine)

Puntatore alla tabella generica.

ByteSize

Numero di byte da allocare.

Per ogni nuovo elemento, il AllocateRoutine viene chiamato per allocare memoria per i dati forniti dal chiamante e una quantità di memoria aggiuntiva da usare dal Rtl... Routine di GenericTableAvl. Si noti che a causa di questa "memoria aggiuntiva", le routine fornite dal chiamante non devono accedere alla prima sizeof(RTL_BALANCED_LINKS) byte di qualsiasi elemento della tabella generica.

[in] FreeRoutine

Un punto di ingresso di una routine di callback deallocazione, dichiarato come segue:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  Buffer
    );

I parametri FreeRoutine sono i seguenti:

Tabella (FreeRoutine)

Puntatore alla tabella generica.

Buffer

Puntatore all'elemento da eliminare.

Rtl... GenericTableAvl routine chiamano il FreeRoutine per deallocare la memoria per gli elementi da eliminare dalla tabella generica. L' FreeRoutine è l'opposto dell'AllocateRoutine.

[in, optional] TableContext

Puntatore facoltativo a un contesto fornito dal chiamante per la tabella generica. Questo parametro può essere NULL.

Valore restituito

Nessuno

Osservazioni

I file system chiamano RtlInitializeGenericTableAvl per inizializzare una tabella generica per archiviare dati specifici del file system, ad esempio informazioni sulla ricerca dei nomi per i file attualmente aperti. L'ordinamento, la struttura e il contenuto degli elementi sono definiti dal chiamante.

I file system devono chiamare RtlInitializeGenericTableAvl per inizializzare la tabella generica prima di usare qualsiasi altra Rtl... GenericTableAvl routine nella nuova tabella generica. La struttura di tabella generica inizializzata deve essere considerata opaca.

Chiamanti del Rtl... Le routine genericTableAvl sono responsabili della sincronizzazione esclusiva dell'accesso alla tabella generica. Un mutex veloce esclusivo è il meccanismo di sincronizzazione più efficiente da usare a questo scopo.

Il chiamante fornito CompareRoutine viene chiamato prima del AllocateRoutine per individuare una posizione appropriata in cui deve essere inserito un nuovo elemento. Viene chiamato anche CompareRoutine prima del FreeRoutine per individuare un elemento da eliminare.

La routine RtlInitializeGenericTableAvl alloca in modo esplicito una tabella generica che utilizza alberi AVL. Uso di questa routine e dell'altro Rtl... Le routine genericTableAvl sono necessarie quando si desiderano tabelle basate su albero AVL e RTL_USE_AVL_TABLES non è definito prima di includere Ntddk.h.

Se si desidera configurare le routine di tabella generiche, Rtl... GenericTable, per usare alberi AVL anziché alberi di riproduzione nel driver, inserire l'istruzione define seguente in un file di intestazione comune prima di includere Ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

I chiamanti di RtlInitializeGenericTableAvl devono essere in esecuzione in IRQL <= DISPATCH_LEVEL. Si noti che se Rtl... Le routine di GenericTableAvl devono essere usate in DISPATCH_LEVEL IRQL, CompareRoutine, AllocateRoutinee FreeRoutine devono essere tutto codice non modificabile e l'AllocateRoutine deve allocare memoria dal pool non di pagine.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
intestazione	ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (vedere la sezione Osservazioni)