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 essere 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 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... GenericTable routine che chiamano la 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 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_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, il AllocateRoutine viene chiamato per allocare memoria per i dati forniti dal chiamante e una quantità di memoria aggiuntiva da usare dal Rtl... Routine genericTable. Si noti che a causa di questa "memoria aggiuntiva", le routine fornite dal chiamante non devono accedere al primo (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) byte di qualsiasi elemento della tabella generica.
[in] FreeRoutine
Un punto di ingresso di una routine di callback 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 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 RtlInitializeGenericTable 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 RtlInitializeGenericTable per inizializzare la tabella generica prima di usare qualsiasi altro Rtl... GenericTable routine 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 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.
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 ad 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 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`
Se si desidera utilizzare 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 con tipizzazione PRTL_AVL_COMPARE_ROUTINE, una routine di callback di allocazione tipizzata PRTL_AVL_ALLOCATE_ROUTINE e una routine di callback deallocazione tipizzata PRTL_AVL_FREE_ROUTINE anziché una routine di callback di deallocazione tipizzata PRTL_GENERIC_xxxsimile.
I chiamanti di RtlInitializeGenericTable devono essere in esecuzione in IRQL <= DISPATCH_LEVEL. Si noti che se Rtl... Le routine di GenericTable devono essere usate in DISPATCH_LEVEL IRQL, CompareRoutine, AllocateRoutinee FreeRoutine devono essere tutto codice non modificabile e 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) |