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 dal 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 nella tabella generica è stato inserito un nuovo elemento con i dati in Buffer; 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 non è possibile inserire il nuovo elemento, ad esempio perché l'AllocateRoutine ha esito negativo), RtlInsertElementGenericTable restituisce NULL.
Osservazioni
Per inserire un elemento, RtlInsertElementGenericTable chiama il 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 relativi dati vengono copiati da buffer nel nuovo elemento. Di conseguenza, il puntatore restituito da RtlInsertElementGenericTable non è mai uguale a Buffer.
Se il CompareRoutine del chiamante restituisce GenericEqual, i dati in Buffer vengono duplicati per un elemento esistente nella tabella generica. In questo caso, RtlInsertElementGenericTable non aggiunge il nuovo elemento (e pertanto non chiama il AllocateRoutine), perché una tabella generica non può avere elementi duplicati.
Se nella tabella generica esiste già un elemento corrispondente, RtlInsertElementGenericTable restituisce un puntatore ai dati dell'elemento esistente e imposta NewElement su FALSE.
Chiamanti di 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.
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 RTL_USE_AVL_TABLES non è definito, è necessario utilizzare il formato AVL delle routine di tabella generiche. Ad esempio, utilizzare 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 è bloccata:
- La memoria allocata dal chiamante in table o in buffer è paginabile.
- Il chiamante fornito CompareRoutine o AllocateRoutine contiene codice pageable.
Fabbisogno
| 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) |