Compartilhar via

Função RtlInsertElementGenericTableFullAvl (ntddk.h)

  • Artigo

A rotina de 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 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.

[in] NodeOrParent

O resultado da pesquisa de uma chamada anterior para RtlLookupElementGenericTableFullAvl. Esse valor indica à rotina RtlInsertElementGenericTableFullAvl rotina 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 do NodeOrParent não foi alterado.

TableFoundNode

A rotina de rtlInsertElementGenericTableFullAvl encontrou uma entrada de tabela cuja chave corresponde aos dados em buffer. NodeOrParent contém um ponteiro para a entrada correspondente.

TableInsertAsLeft

A rotina de rtlInsertElementGenericTableFullAvl não encontrar uma entrada de tabela cuja chave corresponde aos dados no buffer . Se a entrada que RtlInsertElementGenericTableFullAvl pesquisada estivesse na tabela, seria o filho esquerdo da entrada à qual NodeOrParent aponta.

TableInsertAsRight

A rotina de rtlInsertElementGenericTableFullAvl não encontrar uma entrada de tabela cuja chave corresponde aos dados no buffer . Se a entrada que RtlInsertElementGenericTableFullAvl pesquisada estivesse na tabela, seria o filho certo da entrada à qual NodeOrParent aponta.

[in] SearchResult

Um ponteiro para uma entrada de tabela. Se o RtlInsertElementGenericTableFullAvl rotina corresponder a uma entrada, NodeOrParent aponta para a entrada correspondente. Se a rotina rtlInsertElementGenericTableFullAvl não encontrar uma correspondência, NodeOrParent aponta para a entrada que seria o pai da entrada que rtlInsertElementGenericTableFullAvl rotina estava procurando.

Valor de retorno

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 poderá inserir a nova entrada (por exemplo, porque o allocateRoutine falha), RtlInsertElementGenericTableFullAvl retorna NULL .

Observações

Para inserir uma entrada, RtlInsertElementGenericTableFullAvl chama o CompareRoutine e AllocateRoutine que foram registrados quando a tabela genérica foi inicializada pelo 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 de buffer para a nova entrada. Assim, o ponteiro retornado por rtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl retornará um ponteiro para os dados da entrada existente e definirá NewElement para false.

Se ainda não houver nenhuma entrada correspondente na tabela,rtlInsertElementGenericTableFullAvl rotina 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 o tamanho do bufferSize + de(BALANCED_LINKS). O chamador não deve usar o primeiro tamanho de(BALANCED_LINKS) bytes da memória alocada pelo AllocateRoutine.

Chamadores doRtl.. 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 RtlInsertElementGenericTableFullAvl rotina funciona apenas 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 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 deverão 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 no Windows XP e versões posteriores dos sistemas operacionais Windows.
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)

Consulte também

rtlDeleteElementGenericTable

rtlInitializeGenericTable