Função RtlEnumerateGenericTableLikeADirectory (ntddk.h)

  • Artigo

A rotina RtlEnumerateGenericTableLikeADirectory retorna os elementos de uma tabela genérica, um por um, em ordem de ordenação.

Sintaxe

NTSYSAPI PVOID RtlEnumerateGenericTableLikeADirectory(
  [in]           PRTL_AVL_TABLE          Table,
  [in, optional] PRTL_AVL_MATCH_FUNCTION MatchFunction,
  [in, optional] PVOID                   MatchData,
  [in]           ULONG                   NextFlag,
  [in, out]      PVOID                   *RestartKey,
  [in, out]      PULONG                  DeleteCount,
  [in]           PVOID                   Buffer
);

Parâmetros

[in] Table

Um ponteiro para a RTL_AVL_TABLE tabela DesvL (AVL) que será enumerada.

[in, optional] MatchFunction

Uma função de correspondência que determina quais entradas devem ser retornadas. Se não for especificado, todos os nós serão retornados.

[in, optional] MatchData

Os dados a serem passados para a função de correspondência.

[in] NextFlag

Se RestartKey não for NULL, um valor true indicará que a enumeração ignorará um elemento. Se FALSE , a enumeração será retomada de onde parou na chamada anterior para RtlEnumerateGenericTableLikeADirectory. Se RestartKey for NULL, um valor true instruiRtlEnumerateGenericTableLikeADirectory a retornar a próxima entrada na árvore após a entrada que corresponde aos dados no Buffer. Um valor false instruiRtlEnumerateGenericTableLikeADirectory a retornar a entrada na árvore que corresponde aos dados no Buffer.

[in, out] RestartKey

Um valor que determina onde começar ou retomar a enumeração de elementos de tabela genéricos. Se RestartKey for NULL, a enumeração começará ou será retomada da posição descrita em Buffer. Se não for NULL, a enumeração será retomada do ponto que RestartKey indica. No retorno, RestartKey contém um valor que indica o local na árvore em que a enumeração parou. Na próxima chamada para RtlEnumerateGenericTableLikeADirectory , o chamador deve passar o mesmo valor de volta para informar RtlEnumerateGenericTableLikeADirectory onde retomar a enumeração. O exemplo de código a seguir ilustra como fazer isso:

NextFlag = FALSE;
RestartKey = NULL;
DeleteCount = 0;
// Initialize Buffer for start/resume point
Buffer = ...
for (ptr = NULL; ptr != NULL;  ) {
  // Value returned in RestartKey will be passed back in
  // on following call (iteration):
  ptr = RtlEnumerateGenericTableLikeADirectory(
      &MyTable, NULL, NULL, TRUE, &RestartKey,
      &DeleteCount, &Buffer, sizeof(LONG) );
      ...
  // The value output in RestartKey will still be in
  // RestartKey when the
  // RtlEnumerationGenericTableLikeADirectory routine
  // is called in the next iteration of this loop.
  // This ensures that the enumeration will pick up
  // where it left off.
}

Se um nó for excluído da árvore entre chamadas para RtlEnumerateGenericTableLikeADirectory, a enumeração será retomada da posição na árvore descrita em Buffer, independentemente do valor de RestartKey.

[in, out] DeleteCount

Na saída, um valor que indica a contagem atual de entradas excluídas da tabela. O chamador deve passar esse valor novamente na próxima chamada para RtlEnumerateGenericTableLikeADirectory. Esse valor ajuda a rotina RtlEnumerateGenericTableLikeADirectory a determinar se as exclusões da tabela ocorreram entre chamadas para RtlEnumerateGenericTableLikeADirectory. Se as exclusões tiverem ocorrido, a enumeração será retomada com a entrada da tabela que corresponde aos dados em Buffer e não com a entrada de tabela indicada por RestartKey. Se RestartKey for NULL, esse parâmetro não terá efeito na enumeração .

[in] Buffer

Uma expressão de chave que determina onde iniciar a enumeração, quando RestartKey é NULL. O chamador pode passar uma chave salva que corresponda a uma entrada específica na tabela e a enumeração começará na entrada especificada pela chave salva, desde que RestartKey seja NULL e NextFlag seja FALSE. Para retornar a chave que segue imediatamente uma chave salva, passe a chave aqui, defina RestartKey como NULL e NextFlag como TRUE. Se a chave salva tiver sido excluída, a enumeração começará com a próxima chave correspondente.

Retornar valor

A rotina RtlEnumerateGenericTableLikeADirectory retorna um ponteiro para uma estrutura definida pelo usuário associada ao próximo elemento de tabela na enumeração . Se não houver mais elementos novos para retornar, o valor retornado será NULL.

Comentários

A rotina RtlEnumerateGenericTableLikeADirectory fornece um meio seguro para enumerar uma tabela genérica entre operações intermixadas de inserção e exclusão. Começando com o nome da primeira chave correspondente, RtlEnumerateGenericTableLikeADirectory retorna cada nome na tabela exatamente uma vez, a menos que o nome tenha sido inserido ou excluído durante a enumeração. Quando um nome de chave é inserido ou excluído durante uma enumeração (ou seja, entre chamadas para RtlEnumerateGenericTableLikeADirectory), ele pode ou não ser incluído na enumeração. Se esses nomes são incluídos depende do estado do nome quando RtlEnumerateGenericTableLikeADirectory processa o intervalo de diretórios no qual o nome é encontrado.

Há quatro rotinas que você pode usar para enumerar uma tabela genérica:

Por padrão, o sistema operacional usa árvores de reprodução para implementar tabelas genéricas, mas a rotina RtlEnumerateGenericTableLikeADirectory só funciona com árvores Desvelsky/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 define 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.

Os chamadores de RtlEnumerateGenericTableLikeADirectory devem estar em execução em IRQL <= APC_LEVEL se uma das seguintes condições for mantida:

  • A memória alocada pelo chamador em Table ou em Buffer é paginável.

  • O MatchFunction fornecido pelo chamador contém código paginável.

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 <= APC_LEVEL (consulte a seção Comentários)

Confira também

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable