Função RtlInitializeGenericTableAvl (ntddk.h)

Artigo
03/08/2023

A rotina RtlInitializeGenericTableAvl inicializa uma tabela genérica usando árvores Adelson-Velsky/Landis (AVL).

Sintaxe

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                     TableContext
);

Parâmetros

[out] Table

Um ponteiro para um buffer alocado pelo chamador, que deve ter pelo menos tamanho(RTL_AVL_TABLE) bytes de tamanho, para conter a estrutura de tabela genérica inicializada.

[in] CompareRoutine

Um ponto de entrada de uma rotina de retorno de chamada de comparação, declarado da seguinte maneira:

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    );

Os parâmetros CompareRoutine são os seguintes:

Tabela (CompareRoutine)

Um ponteiro para a tabela genérica.

FirstStruct

Um ponteiro para o primeiro item a ser comparado.

SecondStruct

Um ponteiro para o segundo item a ser comparado.

A CompareRoutine deve acompanhar estritamente a ordenação de todos os elementos na tabela genérica para que possa identificar qualquer elemento específico. A estrutura definida pelo chamador para dados de elemento geralmente inclui um membro cujo valor é exclusivo e pode ser usado como uma chave de classificação. Todas as Rtl... As rotinas GenericTableAvl que chamam a CompareRoutine assumem um ponteiro de buffer como um parâmetro, que é passado por sua vez para a CompareRoutine. O buffer contém um valor de chave fornecido pelo chamador a ser correspondido pela CompareRoutine com a chave do elemento que está sendo pesquisado.

Considerando dois desses valores de chave, a CompareRoutine retorna GenericLessThan, GenericGreaterThan ou GenericEqual.

[in] AllocateRoutine

Um ponto de entrada de uma rotina de retorno de chamada de alocação, declarado da seguinte maneira:

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in CLONG  ByteSize
    );

Os parâmetros AllocateRoutine são os seguintes:

Tabela (AllocateRoutine)

Um ponteiro para a tabela genérica.

ByteSize

O número de bytes a serem alocados.

Para cada novo elemento, AllocateRoutine é chamado para alocar memória para dados fornecidos pelo chamador, além de alguma memória adicional para uso pelo Rtl... Rotinas GenericTableAvl . Observe que, devido a essa "memória adicional", as rotinas fornecidas pelo chamador não devem acessar os primeiros bytes sizeof(RTL_BALANCED_LINKS) de qualquer elemento na tabela genérica.

[in] FreeRoutine

Um ponto de entrada de uma rotina de retorno de chamada de desalocação, declarado da seguinte maneira:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  Buffer
    );

Os parâmetros de FreeRoutine são os seguintes:

Tabela (FreeRoutine)

Um ponteiro para a tabela genérica.

Buffer

Um ponteiro para o elemento que está sendo excluído.

Rtl... As rotinas GenericTableAvl chamam a FreeRoutine para desalocar a memória para que os elementos sejam excluídos da tabela genérica. A FreeRoutine é o oposto da AllocateRoutine.

[in, optional] TableContext

Um ponteiro opcional para um contexto fornecido pelo chamador para a tabela genérica. Este parâmetro pode ser NULL.

Retornar valor

Nenhum

Comentários

Os sistemas de arquivos chamam RtlInitializeGenericTableAvl para inicializar uma tabela genérica para armazenar dados específicos do sistema de arquivos, como informações de pesquisa de nome para arquivos abertos no momento. A ordem de classificação, a estrutura e o conteúdo dos elementos são definidos pelo chamador.

Os sistemas de arquivos devem chamar RtlInitializeGenericTableAvl para inicializar a tabela genérica antes de usar qualquer outra Rtl... Rotinas GenericTableAvl na nova tabela genérica. A estrutura de tabela genérica inicializada deve ser considerada opaca.

Chamadores do Rtl... 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.

A CompareRoutine fornecida pelo chamador é chamada antes de AllocateRoutine para localizar um local apropriado no qual um novo elemento deve ser inserido. A CompareRoutine também é chamada antes da FreeRoutine para localizar um elemento a ser excluído.

A rotina RtlInitializeGenericTableAvl aloca explicitamente uma tabela genérica que usa árvores AVL. Uso dessa rotina e do outro Rtl... As rotinas GenericTableAvl são necessárias quando as tabelas baseadas em árvore AVL são desejadas e RTL_USE_AVL_TABLES não é definida antes de incluir Ntddk.h.

Se você quiser configurar as rotinas genéricas de tabela, Rtl... GenericTable, 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`

Os chamadores de RtlInitializeGenericTableAvl devem estar em execução em IRQL <= DISPATCH_LEVEL. Observe que se Rtl... As rotinas GenericTableAvl devem ser usadas em IRQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine e FreeRoutine devem ser código não paginável e a AllocateRoutine deve alocar memória de pool nãopagado.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	ntddk.h (inclua Ntddk.h, Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (consulte a seção Comentários)