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 pelo chamador, que deve ter pelo menos tamanho(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 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... Rotinas genericTable que chamam a CompareRoutine tomam 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_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, AllocateRoutine é chamado para alocar memória para dados fornecidos pelo chamador, além de alguma memória adicional para uso pelo Rtl... Rotinas 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 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 genericTable 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 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... Rotinas genericTable na nova tabela genérica. A estrutura de tabela genérica inicializada deve ser considerada opaca.
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.
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.
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 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 inicializada RTL_AVL_TABLE tabela no buffer para o qual o parâmetro Table aponta. Na chamada para RtlInitializeGenericTableAvl, o chamador deve passar uma rotina de retorno de chamada de comparação do tipo PRTL_AVL_COMPARE_ROUTINE, uma rotina de retorno de chamada de alocação do 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 do tipo PRTL_GENERIC_Xxx.
Os chamadores de RtlInitializeGenericTable devem estar em execução em IRQL <= DISPATCH_LEVEL. Observe que se Rtl... As rotinas genericTable devem ser usadas em IRQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine e FreeRoutine devem ser código não pagá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) |