Função RtlInitializeGenericTable (ntddk.h)

A rotina rtlInitializeGenericTable inicializa uma tabela genérica.

Sintaxe

NTSYSAPI VOID RtlInitializeGenericTable(
  [out]          PRTL_GENERIC_TABLE            Table,
  [in]           PRTL_GENERIC_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_GENERIC_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_GENERIC_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                         TableContext
);

Parâmetros

[out] Table

Um ponteiro para um buffer alocado por chamador, que deve ter pelo menos tamanhos de(RTL_GENERIC_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_GENERIC_COMPARE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    ); 

Os parâmetros de 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.

O 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. Todos Rtl... As rotinas de GenericTable que chamam o CompareRoutine usar um ponteiro de buffer como um parâmetro, que é passado por sua vez para o compareroutine. O buffer contém um valor de chave fornecido pelo chamador a ser correspondido pelo CompareRoutine com a chave do elemento que está sendo pesquisado.

Considerando dois desses valores principais, o 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_GENERIC_ALLOCATE_ROUTINE) (
    __in struct _RTL_GENERIC_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, o AllocateRoutine é chamado para alocar memória para dados fornecidos pelo chamador, além de alguma memória adicional para uso pelo Rtl... Rotinas de GenericTable. Observe que, devido a essa "memória adicional", as rotinas fornecidas pelo chamador não devem acessar os primeiros bytes (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) 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_GENERIC_FREE_ROUTINE) (
    __in struct _RTL_GENERIC_TABLE  *Table,
    __in PVOID  Buffer
    );

Os parâmetros de do 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 de genericTable chamam a FreeRoutine para desalocar a memória para que os elementos sejam excluídos da tabela genérica. O FreeRoutine é o oposto do AllocateRoutine.

[in, optional] TableContext

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

Valor de retorno

Nenhum

Observações

Os sistemas de arquivos chamam RtlInitializeGenericTable 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 RtlInitializeGenericTable para inicializar a tabela genérica antes de usar qualquer outra Rtl... GenericTable rotinas na nova tabela genérica. A estrutura de tabela genérica inicializada deve ser considerada opaca.

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

O CompareRoutine fornecido pelo chamador é chamado antes do AllocateRoutine para localizar um local apropriado no qual um novo elemento deve ser inserido. O CompareRoutine também é chamado antes do de FreeRoutine para localizar um elemento a ser excluído.

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 1`

Se você quiser usar tabelas AVL e se RTL_USE_AVL_TABLES não estiver definido, deverá usar a forma AVL das rotinas de tabela genéricas. Por exemplo, use a rotina rtlInitializeGenericTableAvl em vez de rtlInitializeGenericTable. RtlInitializeGenericTableAvl retorna uma estrutura de tabela de RTL_AVL_TABLE inicializada no buffer para o qual o parâmetro Table. Na chamada para rtlInitializeGenericTableAvl, o chamador deve passar uma rotina de retorno de chamada de comparação tipo PRTL_AVL_COMPARE_ROUTINE, uma rotina de retorno de chamada de alocação tipo PRTL_AVL_ALLOCATE_ROUTINE e uma rotina de retorno de chamada de desalocação tipo PRTL_AVL_FREE_ROUTINE em vez das rotinas semelhantes PRTL_GENERIC_xxxdigitadas.

Os chamadores de RtlInitializeGenericTable devem estar em execução no IRQL <= DISPATCH_LEVEL. Observe que se Rtl... As rotinas de GenericTable devem ser usadas no IRQL DISPATCH_LEVEL, os deCompareRoutine, AllocateRoutinee freeroutine devem ser todos código não pageable e o allocateRoutine deve alocar memória do pool nãopagado.

Requisitos

Consulte também

ExInitializeFastMutex

rtlDeleteElementGenericTable

rtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

rtlGetElementGenericTable

rtlInsertElementGenericTable

RtlLookupElementGenericTable

RtlNumberGenericTableElements