Funzione RtlInsertElementGenericTableAvl (ntddk.h)
La routine RtlInsertElementGenericTableAvl aggiunge una nuova voce a una tabella generica.
Sintassi
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parametri
[in] Table
Puntatore a una tabella Adelson-Velsky/Landis (AVL) generica (RTL_AVL_TABLE) inizializzata da una chiamata a RtlInitializeGenericTableAvl.
[in] Buffer
Buffer allocato dal chiamante che contiene i dati utente da copiare nel nuovo elemento. Per altre informazioni, vedere RtlInitializeGenericTableAvl.
[in] BufferSize
Dimensioni in byte di dati nel buffer .
[out, optional] NewElement
Nell'output, un valore di TRUE indica che l'inserimento del nuovo elemento nella tabella generica ha avuto esito positivo. Il valore FALSE indica che l'inserimento non è riuscito.
Valore restituito
RtlInsertElementGenericTableAvl restituisce un puntatore ai dati utente per la voce appena inserita oppure i dati utente per una voce corrispondente già presente nella tabella generica. Se non viene trovata alcuna voce corrispondente, ma RtlInsertElementGenericTableAvl non è possibile inserire la nuova voce, ad esempio perché l'AllocateRoutine ha esito negativo), RtlInsertElementGenericTableAvl restituisce NULL.
Osservazioni
Per inserire una voce, RtlInsertElementGenericTableAvl chiama CompareRoutine e AllocateRoutine registrati quando la tabella generica è stata inizializzata da RtlInitializeGenericTableAvl. Dopo aver inserito la nuova voce, RtlInsertElementGenericTableAvl ribilancia l'albero dei collegamenti AVL.
Quando viene inserita una nuova voce nella tabella, i relativi dati vengono copiati da buffer nella nuova voce. Di conseguenza, il puntatore restituito da RtlInsertElementGenericTableAvl non è mai uguale a Buffer.
Se il CompareRou tine del chiamante restituisce GenericEqual, si presuppone che i dati in Buffer duplicino i dati per una voce esistente nella tabella generica. In questo caso, RtlInsertElementGenericTableAvl non aggiunge la nuova voce (e pertanto non chiama il AllocateRoutine), perché una tabella generica non può avere voci duplicate.
Se nella tabella generica esiste già una voce corrispondente, RtlInsertElementGenericTableAvl restituisce un puntatore ai dati della voce esistente e imposta NewElement su FALSE.
Se non è già presente alcuna voce corrispondente nella tabella,RtlInsertElementGenericTableAvl routine alloca spazio sufficiente per i dati utente della nuova voce (BufferSize) più i collegamenti associati alla nuova voce. Pertanto, il numero totale di byte sarà almeno BufferSize + sizeof(RTL_BALANCED_LINKS). Il chiamante non deve usare il primo sizeof(RTL_BALANCED_LINKS) byte della memoria allocata AllocateRoutine.
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 a questo scopo.
Per impostazione predefinita, il sistema operativo usa alberi splay per implementare tabelle generiche, ma la RtlInsertElementGenericTableAvl routine funziona solo con alberi Adelson-Velsky/Landis (AVL). Per 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 RtlInsertElementGenericTableAvl 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 |
|---|---|
| client minimo supportato | Disponibile a partire da Windows XP. |
| 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) |