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 por 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 VERDADEIRO se um novo elemento com os dados no buffer foi inserido na tabela genérica; ou FALSE se o novo elemento não tiver sido inserido.

Valor de retorno

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 o allocateRoutine falhar), RtlInsertElementGenericTable retornará NULL.

Observações

Para inserir um elemento, RtlInsertElementGenericTable chama o CompareRoutine e allocateRoutine que foram registrados quando a tabela genérica foi inicializada por RtlInitializeGenericTable. Depois de inserir o novo elemento, RtlInsertElementGenericTable reequilibra a árvore de link de reprodução.

Quando um novo elemento é inserido na tabela, seus dados são copiados de buffer para o novo elemento. Portanto, o ponteiro retornado por rtlInsertElementGenericTable nunca é igual a buffer.

Se o CompareRoutine do chamador retornar GenericEqual, os dados no do 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 o 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 para 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 Desassocupadas/Landis (AVL). Se você quiser configurar as rotinas de tabela genéricas para usar árvores AVL em vez de reproduzir árvores 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 RtlInsertElementGenericTable 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

Consulte também

rtlDeleteElementGenericTable

rtlInitializeGenericTable