Função RtlInsertElementGenericTable (ntddk.h)
A rotina RtlInsertElementGenericTable adiciona um novo elemento a uma tabela genérica.
Sintaxe
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parâmetros
[in] Table
Ponteiro para a tabela genérica (RTL_GENERIC_TABLE). A tabela deve ter sido inicializada chamando RtlInitializeGenericTable.
[in] Buffer
Ponteiro para um buffer alocado pelo chamador que contém dados a serem copiados para o novo elemento. Para obter mais informações, consulte a descrição de RtlInitializeGenericTable.
[in] BufferSize
Número de bytes a serem alocados para dados fornecidos pelo chamador quando o novo elemento é inserido.
[out, optional] NewElement
Ponteiro para uma variável que recebe TRUE se um novo elemento com os dados em Buffer foi inserido na tabela genérica; ou FALSE se o novo elemento não foi inserido.
Retornar valor
RtlInsertElementGenericTable retorna um ponteiro para os dados associados do elemento recém-inserido ou retorna um ponteiro para os dados do elemento existente se um elemento correspondente já existir na tabela genérica. Se nenhum elemento correspondente for encontrado, mas o novo elemento não puder ser inserido (por exemplo, porque AllocateRoutine falha), RtlInsertElementGenericTable retornará NULL.
Comentários
Para inserir um elemento, RtlInsertElementGenericTable chama CompareRoutine e AllocateRoutine que foram registrados quando a tabela genérica foi inicializada por RtlInitializeGenericTable. Depois de inserir o novo elemento, RtlInsertElementGenericTable rebalancea a árvore de link de reprodução.
Quando um novo elemento é inserido na tabela, seus dados são copiados do Buffer para o novo elemento. Portanto, o ponteiro retornado por RtlInsertElementGenericTable nunca é igual a Buffer.
Se CompareRoutine do chamador retornar GenericEqual, os dados em Buffer serão assumidos para duplicar os dados de um elemento existente na tabela genérica. Nesse caso, RtlInsertElementGenericTable não adiciona o novo elemento (e, portanto, não chama AllocateRoutine), porque uma tabela genérica não pode ter elementos duplicados.
Se já existir um elemento correspondente na tabela genérica, RtlInsertElementGenericTable retornará um ponteiro para os dados do elemento existente e definirá NewElement como FALSE.
Chamadores do Rtl. As rotinas genericTable 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. Em algumas circunstâncias, as operações em uma árvore de reprodução tornarão a árvore profunda e estreita e podem até mesmo transformá-la em uma linha reta. Árvores muito profundas degradam o desempenho das pesquisas. Você pode garantir uma implementação de árvore mais equilibrada e superficial de tabelas genéricas usando árvores Adelson-Velsky/Landis (AVL). Se você quiser 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 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 RtlInsertElementGenericTable devem estar em execução no IRQL < DISPATCH_LEVEL se uma das seguintes condições for mantida:
- A memória alocada pelo chamador na Tabela ou no Buffer é paginável.
- O CompareRoutine fornecido pelo chamador ou AllocateRoutine contém código paginável.
Requisitos
| Requisito | Valor |
|---|---|
| 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) |