Funzione RtlInsertElementGenericTable (ntddk.h)
La routine RtlInsertElementGenericTable aggiunge un nuovo elemento a una tabella generica.
Sintassi
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parametri
[in] Table
Puntatore alla tabella generica (RTL_GENERIC_TABLE). La tabella deve essere stata inizializzata chiamando RtlInitializeGenericTable.
[in] Buffer
Puntatore a un buffer allocato del chiamante contenente i dati da copiare nel nuovo elemento. Per altre informazioni, vedere la descrizione di RtlInitializeGenericTable.
[in] BufferSize
Numero di byte da allocare per i dati forniti dal chiamante quando viene inserito il nuovo elemento.
[out, optional] NewElement
Puntatore a una variabile che riceve TRUE se un nuovo elemento con i dati in Buffer è stato inserito nella tabella generica; o FALSE se il nuovo elemento non è stato inserito.
Valore restituito
RtlInsertElementGenericTable restituisce un puntatore ai dati associati all'elemento appena inserito oppure restituisce un puntatore ai dati dell'elemento esistente se esiste già un elemento corrispondente nella tabella generica. Se non viene trovato alcun elemento corrispondente, ma il nuovo elemento non può essere inserito (ad esempio, perché allocateRoutine ha esito negativo), RtlInsertElementGenericTable restituisce NULL.
Commenti
Per inserire un elemento, RtlInsertElementGenericTable chiama CompareRoutine e AllocateRoutine registrati quando la tabella generica è stata inizializzata da RtlInitializeGenericTable. Dopo aver inserito il nuovo elemento, RtlInsertElementGenericTable ribilancia l'albero dei collegamenti di riproduzione.
Quando un nuovo elemento viene inserito nella tabella, i dati vengono copiati da Buffer nel nuovo elemento. Pertanto il puntatore restituito da RtlInsertElementGenericTable non è mai uguale a Buffer.
Se il chiamante CompareRoutinerestituisce GenericEqual, i dati in Buffer vengono duplicati per un elemento esistente nella tabella generica. In questo caso, RtlInsertElementGenericTable non aggiunge il nuovo elemento (e quindi non chiama AllocateRoutine), perché una tabella generica non può avere elementi duplicati.
Se esiste già un elemento corrispondente nella tabella generica, RtlInsertElementGenericTable restituisce un puntatore ai dati dell'elemento esistente e imposta NewElement su FALSE.
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 per questo scopo.
Per impostazione predefinita, il sistema operativo usa alberi di riproduzione per implementare tabelle generiche. In alcune circostanze, le operazioni su un albero di riproduzione 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 delle tabelle generiche usando alberi Adelson-Velsky/Landis (AVL). Se si desidera configurare le routine di tabella generiche 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
Se RTL_USE_AVL_TABLES non è definito, è necessario usare il formato AVL delle routine di tabella generiche. Ad esempio, usare la routine RtlInsertElementGenericTableAvl anziché RtlInsertElementGenericTable. Nella chiamata a RtlInsertElementGenericTableAvl, il chiamante deve passare una struttura di tabella RTL_AVL_TABLE anziché RTL_GENERIC_TABLE.
I chiamanti di RtlInsertElementGenericTable devono essere eseguiti in IRQL < DISPATCH_LEVEL se una delle condizioni seguenti contiene:
- La memoria allocata dal chiamante in Table o in Buffer è paginabile.
- Il chiamante fornito da CompareRoutine o AllocateRoutine contiene codice paginabile.
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Intestazione | ntddk.h (include Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (vedere la sezione Osservazioni) |