Funzione RtlInitializeGenericTable (ntddk.h)

La routine RtlInitializeGenericTable inizializza una tabella generica.

Sintassi

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

Parametri

[out] Table

Puntatore a un buffer allocato dal chiamante, che deve avere dimensioni di almeno sizeof(RTL_GENERIC_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_GENERIC_COMPARE_ROUTINE) (
    __in struct _RTL_GENERIC_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 rigorosamente dell'ordinamento di tutti gli elementi nella 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. Tutte le Rtl... Le routine GenericTable che chiamano CompareRoutine accettano un puntatore del buffer come parametro, che viene passato a sua volta a CompareRoutine. Il buffer contiene un valore di chiave fornito dal chiamante da associare a CompareRoutine alla chiave dell'elemento in cui viene eseguita la ricerca.

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

[in] AllocateRoutine

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

PVOID
(*PRTL_GENERIC_ALLOCATE_ROUTINE) (
    __in struct _RTL_GENERIC_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, allocateRoutine viene chiamato per allocare memoria per i dati forniti dal chiamante, oltre ad alcune memoria aggiuntiva da usare da Rtl... Routine GenericTable . Si noti che a causa di questa "memoria aggiuntiva", le routine fornite dal chiamante non devono accedere al primo byte (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) di qualsiasi elemento nella tabella generica.

[in] FreeRoutine

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

VOID
(*PRTL_GENERIC_FREE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in PVOID  Buffer
    );

I parametri FreeRoutine sono i seguenti:

Tabella (FreeRoutine)

Puntatore alla tabella generica.

Buffer

Puntatore all'elemento da eliminare.

Rtl... Le routine GenericTable 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 RtlInitializeGenericTable per inizializzare una tabella generica per archiviare dati specifici del file system, ad esempio le 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 RtlInitializeGenericTable per inizializzare la tabella generica prima di usare qualsiasi altro Rtl... Routine GenericTable nella nuova tabella generica. La struttura di tabella generica inizializzata deve essere considerata opaca.

Chiamanti del Rtl... Le routine GenericTable 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 compareRoutine fornito viene chiamato prima di AllocateRoutine per individuare una posizione appropriata in cui inserire un nuovo elemento. CompareRoutine viene chiamato anche prima di FreeRoutine per individuare un elemento da eliminare.

Per impostazione predefinita, il sistema operativo usa alberi splay per implementare tabelle generiche. In alcune circostanze, le operazioni su un albero splay renderanno l'albero profondo e stretto e potrebbe anche trasformarlo in una linea retta. Gli alberi molto profondi riducono le prestazioni delle ricerche. È possibile garantire un'implementazione albero più bilanciata e superficiale di tabelle generiche usando alberi Adelson-Velsky/Landis (AVL). Se si desidera configurare le routine di tabella generiche per l'uso di alberi AVL anziché alberi Splay nel driver, inserire l'istruzione define seguente in un file di intestazione comune prima di includere Ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

Se si desidera utilizzare le tabelle AVL e se RTL_USE_AVL_TABLES non è definito, è necessario utilizzare il formato AVL delle routine di tabella generiche. Ad esempio, utilizzare la routine RtlInitializeGenericTableAvl anziché RtlInitializeGenericTable. RtlInitializeGenericTableAvl restituisce una struttura di tabella RTL_AVL_TABLE inizializzata nel buffer in cui punta il parametro Table . Nella chiamata a RtlInitializeGenericTableAvl, il chiamante deve passare una routine di callback di confronto tipizzata PRTL_AVL_COMPARE_ROUTINE, una routine di callback di allocazione tipizzata PRTL_AVL_ALLOCATE_ROUTINE e una routine di callback di deallocazione tipizzata PRTL_AVL_FREE_ROUTINE anziché le routine di callback di tipo PRTL_GENERIC_Xxx simili.

I chiamanti di RtlInitializeGenericTable devono essere in esecuzione in IRQL <= DISPATCH_LEVEL. Si noti che se Rtl... Le routine GenericTable devono essere usate in irQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine e FreeRoutine devono essere tutti codice non modificabile e AllocateRoutine deve allocare memoria da un pool non di paging.

Requisiti

Vedi anche

ExInitializeFastMutex

RtlDeleteElementGenericTable

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable

RtlInsertElementGenericTable

RtlLookupElementGenericTable

RtlNumberGenericTableElements