Funzione RtlInsertElementGenericTableFullAvl (ntddk.h)
La routine RtlInsertElementGenericTableFullAvl aggiunge una nuova voce a una tabella generica.
Sintassi
NTSYSAPI PVOID RtlInsertElementGenericTableFullAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement,
[in] PVOID NodeOrParent,
[in] TABLE_SEARCH_RESULT SearchResult
);
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 TRUE indica che l'inserimento del nuovo elemento nella tabella generica è riuscito. Il valore FALSE indica che l'inserimento non è riuscito.
[in] NodeOrParent
Risultato della ricerca di una chiamata precedente a RtlLookupElementGenericTableFullAvl. Questo valore indica alla routine RtlInsertElementGenericTableFullAvl se l'albero è attualmente vuoto o se non è vuoto, se inserire la nuova voce a sinistra o a destra della voce padre. Il parametro SearchResult può avere uno dei valori seguenti:
TableEmptyTree
L'albero era vuoto. Il contenuto di NodeOrParentnon è stato modificato.
TableFoundNode
La routine RtlInsertElementGenericTableFullAvl ha trovato una voce di tabella la cui chiave corrisponde ai dati in Buffer. NodeOrParent contiene un puntatore alla voce corrispondente.
TableInsertAsLeft
La routine RtlInsertElementGenericTableFullAvlnon ha trovato una voce di tabella la cui chiave corrisponde ai dati in Buffer. Se la voce che RtlInsertElementGenericTableFullAvl ha cercato si trovasse nella tabella, sarebbe l'elemento figlio sinistro della voce a cui punta NodeOrParent .
TableInsertAsRight
La routine RtlInsertElementGenericTableFullAvlnon ha trovato una voce di tabella la cui chiave corrisponde ai dati in Buffer. Se la voce che RtlInsertElementGenericTableFullAvl ha cercato si trovasse nella tabella, sarebbe l'elemento figlio corretto della voce a cui punta NodeOrParent .
[in] SearchResult
Puntatore a una voce di tabella. Se la routine RtlInsertElementGenericTableFullAvl corrisponde a una voce, NodeOrParent punta alla voce corrispondente. Se la routine RtlInsertElementGenericTableFullAvl non riesce a trovare una corrispondenza, NodeOrParent punta alla voce che sarebbe l'elemento padre della voce che RtlInsertElementGenericTableFullAvl stava cercando.
Valore restituito
RtlInsertElementGenericTableFullAvl restituisce un puntatore ai dati utente per la voce appena inserita o i dati utente per una voce corrispondente già presente nella tabella generica. Se non viene trovata alcuna voce corrispondente, ma RtlInsertElementGenericTableFullAvl non può inserire la nuova voce, ad esempio perché AllocateRoutine ha esito negativo, RtlInsertElementGenericTableFullAvl restituisce NULL.
Commenti
Per inserire una voce, RtlInsertElementGenericTableFullAvl chiama CompareRoutine e AllocateRoutine registrati quando la tabella generica è stata inizializzata da RtlInitializeGenericTableAvl. Dopo aver inserito la nuova voce, RtlInsertElementGenericTableFullAvl ribilancia l'albero dei collegamenti AVL.
Quando viene inserita una nuova voce nella tabella, i relativi dati vengono copiati da Buffer nella nuova voce. Il puntatore restituito da RtlInsertElementGenericTableFullAvl non è quindi mai uguale a Buffer.
Se compareRoutine del chiamante restituisce GenericEqual, si presuppone che i dati in Buffer duplicino i dati per una voce esistente nella tabella generica. In questo caso , RtlInsertElementGenericTableFullAvl non aggiunge la nuova voce (e quindi non chiama AllocateRoutine), perché una tabella generica non può contenere voci duplicate.
Se nella tabella generica esiste già una voce corrispondente, RtlInsertElementGenericTableFullAvl restituisce un puntatore ai dati della voce esistente e imposta NewElement su FALSE.
Se nella tabella non è già presente alcuna voce corrispondente, la routine RtlInsertElementGenericTableFullAvl 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(BALANCED_LINKS). Il chiamante non deve usare i primi byte sizeof(BALANCED_LINKS) della memoria allocata da AllocateRoutine.
Chiamanti delRtl.. 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 routine RtlInsertElementGenericTableFullAvl funziona solo con alberi Adelson-Velsky/Landis (AVL). Per configurare le routine di tabella generiche per l'uso degli alberi AVL anziché degli 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 RTL_USE_AVL_TABLES non è definito, è necessario utilizzare il formato AVL delle routine di tabella generiche. Ad esempio, usare la routine RtlInsertElementGenericTableFullAvl anziché RtlInsertElementGenericTableFull. Nella chiamata a RtlInsertElementGenericTableFullAvl, il chiamante deve passare una struttura di tabella RTL_AVL_TABLE anziché RTL_GENERIC_TABLE.
I chiamanti di RtlInsertElementGenericTableFullAvl devono essere in esecuzione in IRQL < DISPATCH_LEVEL se una delle condizioni seguenti è valida:
- La memoria allocata dal chiamante in Table o in Buffer è paging.
- Il chiamante fornito da CompareRoutine o AllocateRoutine contiene codice di paging.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile in Windows XP e versioni successive dei sistemi operativi Windows. |
| 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) |