Função RtlInsertElementGenericTableFullAvl (ntddk.h)
A rotina RtlInsertElementGenericTableFullAvl adiciona uma nova entrada a uma tabela genérica.
Sintaxe
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
);
Parâmetros
[in] Table
Ponteiro para uma tabela genérica Desiniciar/Landis (AVL) (RTL_AVL_TABLE) que foi inicializada por uma chamada para RtlInitializeGenericTableAvl.
[in] Buffer
Um buffer alocado pelo chamador que contém os dados do usuário a serem copiados para o novo elemento. Para obter mais informações, consulte RtlInitializeGenericTableAvl.
[in] BufferSize
Tamanho em bytes de dados no Buffer.
[out, optional] NewElement
Na saída, um valor true significa que a inserção do novo elemento na tabela genérica foi bem-sucedida. Um valor false significa que a inserção falhou.
[in] NodeOrParent
O resultado da pesquisa de uma chamada anterior para RtlLookupElementGenericTableFullAvl. Esse valor indica à rotina RtlInsertElementGenericTableFullAvl se a árvore está vazia no momento ou se não está vazia, se deseja inserir a nova entrada à esquerda ou à direita da entrada pai. O parâmetro SearchResult pode ter qualquer um dos seguintes valores:
TableEmptyTree
A árvore estava vazia. O conteúdo de NodeOrParentnão foi alterado.
TableFoundNode
A rotina RtlInsertElementGenericTableFullAvl encontrou uma entrada de tabela cuja chave corresponde aos dados no Buffer. NodeOrParent contém um ponteiro para a entrada correspondente.
TableInsertAsLeft
A rotina RtlInsertElementGenericTableFullAvlnão encontrou uma entrada de tabela cuja chave corresponde aos dados no Buffer. Se a entrada que RtlInsertElementGenericTableFullAvl pesquisou estivesse na tabela, seria o filho esquerdo da entrada para a qual NodeOrParent aponta.
TableInsertAsRight
A rotina RtlInsertElementGenericTableFullAvlnão encontrou uma entrada de tabela cuja chave corresponde aos dados no Buffer. Se a entrada que RtlInsertElementGenericTableFullAvl pesquisou estivesse na tabela, ela seria o filho certo da entrada para a qual NodeOrParent aponta.
[in] SearchResult
Um ponteiro para uma entrada de tabela. Se a rotina RtlInsertElementGenericTableFullAvl corresponder a uma entrada, NodeOrParent apontará para a entrada correspondente. Se a rotina RtlInsertElementGenericTableFullAvl não encontrar uma correspondência, NodeOrParent apontará para a entrada que seria o pai da entrada que a rotina RtlInsertElementGenericTableFullAvl estava procurando.
Retornar valor
RtlInsertElementGenericTableFullAvl retorna um ponteiro para os dados do usuário para a entrada recém-inserida ou os dados do usuário para uma entrada correspondente que já está na tabela genérica. Se nenhuma entrada correspondente for encontrada, mas RtlInsertElementGenericTableFullAvl não puder inserir a nova entrada (por exemplo, porque a AllocateRoutine falha), RtlInsertElementGenericTableFullAvl retornará NULL.
Comentários
Para inserir uma entrada, RtlInsertElementGenericTableFullAvl chama CompareRoutine e AllocateRoutine que foram registrados quando a tabela genérica foi inicializada por RtlInitializeGenericTableAvl. Depois de inserir a nova entrada, RtlInsertElementGenericTableFullAvl reequilibra a árvore de link AVL.
Quando uma nova entrada é inserida na tabela, seus dados são copiados do Buffer para a nova entrada. Portanto, o ponteiro retornado por RtlInsertElementGenericTableFullAvl nunca é igual a Buffer.
Se a CompareRoutine do chamador retornar GenericEqual, os dados no Buffer serão considerados duplicados para uma entrada existente na tabela genérica. Nesse caso, RtlInsertElementGenericTableFullAvl não adiciona a nova entrada (e, portanto, não chama a AllocateRoutine), porque uma tabela genérica não pode ter entradas duplicadas.
Se já existir uma entrada correspondente na tabela genérica, RtlInsertElementGenericTableFullAvl retornará um ponteiro para os dados da entrada existente e definirá NewElement como FALSE.
Se ainda não houver nenhuma entrada correspondente na tabela, a rotina RtlInsertElementGenericTableFullAvl alocará espaço suficiente para os dados do usuário da nova entrada (BufferSize) mais os links associados à nova entrada. Portanto, o número total de bytes será pelo menos BufferSize + sizeof(BALANCED_LINKS). O chamador não deve usar os primeiros bytes sizeof(BALANCED_LINKS) da memória alocada pela AllocateRoutine.
Chamadores doRtl. As rotinas GenericTableAvl são responsáveis por sincronizar exclusivamente o acesso à tabela genérica. Um mutex rápido exclusivo é o mecanismo de sincronização mais eficiente a ser usado para essa finalidade.
Por padrão, o sistema operacional usa árvores de reprodução para implementar tabelas genéricas, mas a rotina RtlInsertElementGenericTableFullAvl só funciona com árvores Desvelsky/Landis (AVL). Para configurar as rotinas de tabela genéricas para usar árvores AVL em vez de árvores de reprodução no driver, insira a seguinte instrução define em um arquivo de cabeçalho comum antes de incluir Ntddk.h:
#define RTL_USE_AVL_TABLES 0
Se RTL_USE_AVL_TABLES não estiver definido, você deverá usar a forma AVL das rotinas de tabela genéricas. Por exemplo, use a rotina RtlInsertElementGenericTableFullAvl em vez de RtlInsertElementGenericTableFull. Na chamada para RtlInsertElementGenericTableFullAvl, o chamador deve passar uma estrutura de tabela RTL_AVL_TABLE em vez de RTL_GENERIC_TABLE.
Os chamadores de RtlInsertElementGenericTableFullAvl devem estar em execução no IRQL < DISPATCH_LEVEL se uma das seguintes condições for mantida:
- A memória alocada pelo chamador em Table ou em Buffer é paginável.
- A CompareRoutine ou AllocateRoutine fornecida pelo chamador contém código paginável.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows XP e versões posteriores dos sistemas operacionais Windows. |
| Plataforma de Destino | Universal |
| Cabeçalho | ntddk.h (inclua Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (consulte a seção Comentários) |