Função RtlInsertElementGenericTableAvl (ntddk.h)
A rotina de rtlInsertElementGenericTableAvl adiciona uma nova entrada a uma tabela genérica.
Sintaxe
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parâmetros
[in] Table
Ponteiro para umaRTL_AVL_TABLEtabela AVL (AVL) genérica 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 de .
[out, optional] NewElement
Na saída, um valor de VERDADEIRO significa que a inserção do novo elemento na tabela genérica foi bem-sucedida. Um valor de FALSE significa que a inserção falhou.
Valor de retorno
RtlInsertElementGenericTableAvl 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 RtlInsertElementGenericTableAvl não poderá inserir a nova entrada (por exemplo, porque o AllocateRoutine falha), RtlInsertElementGenericTableAvl retorna NULL.
Observações
Para inserir uma entrada, RtlInsertElementGenericTableAvl chama o CompareRoutine e AllocateRoutine que foram registrados quando a tabela genérica foi inicializada por rtlInitializeGenericTableAvl. Depois de inserir a nova entrada, RtlInsertElementGenericTableAvl reequilibra a árvore de link AVL.
Quando uma nova entrada é inserida na tabela, seus dados são copiados de buffer para a nova entrada. Portanto, o ponteiro retornado por rtlInsertElementGenericTableAvl nunca é igual a buffer.
Se o compareRoutine do chamador retornar GenericEqual, os dados no do Buffer serão assumidos para duplicar os dados de uma entrada existente na tabela genérica. Nesse caso, RtlInsertElementGenericTableAvl não adiciona a nova entrada (e, portanto, não chama o allocateRoutine), porque uma tabela genérica não pode ter entradas duplicadas.
Se já existir uma entrada correspondente na tabela genérica, RtlInsertElementGenericTableAvl retornará um ponteiro para os dados da entrada existente e definirá NewElement como false.
Se ainda não houver nenhuma entrada correspondente na tabela,rtlInsertElementGenericTableAvl rotina alocará espaço suficiente para os dados do usuário de nova entrada (BufferSize) além dos links associados à nova entrada. Portanto, o número total de bytes será pelo menos bufferSize + tamanhos de(RTL_BALANCED_LINKS). O chamador não deve usar o primeiro tamanho de(RTL_BALANCED_LINKS) bytes da memória alocada peloAllocateRoutine.
Chamadores do Rtl.. As rotinas de 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 o RtlInsertElementGenericTableAvl rotina só funciona com árvores Desabilitadas/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 de definição 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 de RtlInsertElementGenericTableAvl em vez de rtlInsertElementGenericTable. Na chamada para RtlInsertElementGenericTableAvl, o chamador deve passar uma estrutura de tabela RTL_AVL_TABLE em vez de RTL_GENERIC_TABLE.
Os chamadores de RtlInsertElementGenericTableAvl devem estar em execução no IRQL < DISPATCH_LEVEL se uma das seguintes condições se mantiver:
- A memória alocada pelo chamador em de Tabela ou no do Buffer é paginável.
- O CompareRoutine fornecido pelo chamador ou AllocateRoutine contém código paginável.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows XP. |
| da Plataforma de Destino | Universal |
| cabeçalho | ntddk.h (inclua Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (consulte a seção Comentários) |