Funzione RtlInitializeGenericTableAvl (ntddk.h)

Articolo
03/05/2024

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 in dimensione, per contenere la struttura di tabella generica inizializzata.

[in] CompareRoutine

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

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

I parametri CompareRoutine sono i seguenti:

Tabella (CompareRoutine)

Puntatore alla tabella generica.

FirstStruct

Puntatore al primo elemento da confrontare.

SecondStruct

Puntatore al secondo elemento da confrontare.

CompareRoutine deve tenere traccia strettamente 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 in genere include un membro il cui valore è univoco e può essere usato come chiave di ordinamento. Tutto Rtl... Routine GenericTableAvl che chiamano CompareRoutine accettano un puntatore del buffer come parametro, che viene passato a sua volta al CompareRoutine. Il buffer contiene un valore di chiave fornito dal chiamante da corrispondere a CompareRoutine alla chiave dell'elemento da cercare.

Dato due valori chiave, CompareRoutine restituisce GenericLessThan, GenericGreaterThan o GenericEqual.

[in] AllocateRoutine

Punto di ingresso di una routine di callback di allocazione, dichiarata 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, AllocatoRoutine viene chiamato per allocare memoria per i dati forniti dal chiamante e una memoria aggiuntiva per l'uso da Rtl... Routine GenericTableAvl . Si noti che a causa di questa routine "memoria aggiuntiva", il chiamante fornito non deve accedere ai primi byte sizeof(RTL_BALANCED_LINKS) di qualsiasi elemento nella tabella generica.

[in] FreeRoutine

Punto di ingresso di una routine di callback deallocation, dichiarata come indicato di seguito:

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

Rtl... Le routine GenericTableAvl chiamano FreeRoutine per deallocare la memoria per gli elementi da eliminare dalla tabella generica. FreeRoutine è l'opposto di 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 altro Rtl... Routine GenericTableAvl 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 per questo scopo.

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

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

Per 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 GenericTableAvl devono essere usate in irQL DISPATCH_LEVEL, compareRoutine, AllocateRoutine e FreeRoutine devono essere tutti codice non modificabili e allocare memoria dal pool non di pagina.

Requisiti

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)