Funzione RtlEnumerateGenericTableLikeADirectory (ntddk.h)

  • Articolo

La routine RtlEnumerateGenericTableLikeADirectory restituisce gli elementi di una tabella generica, uno per uno, nell'ordine delle regole di confronto.

Sintassi

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
);

Parametri

[in] Table

Puntatore alla tabella Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE) che verrà enumerata.

[in, optional] MatchFunction

Funzione di corrispondenza che determina le voci da restituire. Se non specificato, vengono restituiti tutti i nodi.

[in, optional] MatchData

Dati da passare alla funzione di corrispondenza.

[in] NextFlag

Se RestartKey non è NULL, un valore true indica che l'enumerazione ignora un elemento. Se FALSE l'enumerazione riprende dove è stata interrotta nella chiamata precedente a RtlEnumerateGenericTableLikeADirectory. Se RestartKey è NULL, un valore true indica a RtlEnumerateGenericTableLikeADirectory di restituire la voce successiva nell'albero dopo la voce corrispondente ai dati nel buffer. Un valore false indicaa RtlEnumerateGenericTableLikeADirectory di restituire la voce nell'albero corrispondente ai dati nel buffer.

[in, out] RestartKey

Valore che determina dove iniziare o riprendere l'enumerazione degli elementi di tabella generici. Se RestartKey è NULL, l'enumerazione inizia o riprende dalla posizione descritta in Buffer. In caso contrario , l'enumerazione riprende dal punto che RestartKey indica. In caso di ritorno, RestartKey contiene un valore che indica la posizione nell'albero in cui l'enumerazione è stata interrotta. Nella chiamata successiva al chiamante RtlEnumerateGenericTableLikeADirectory deve passare lo stesso valore per informare RtlEnumerateGenericTableLikeADirectory dove riprendere l'enumerazione. Nell'esempio di codice seguente viene illustrato come eseguire questa operazione:

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 un nodo viene eliminato dall'albero tra le chiamate a RtlEnumerateGenericTableLikeADirectory, l'enumerazione riprende dalla posizione dell'albero descritto in Buffer, indipendentemente dal valore di RestartKey.

[in, out] DeleteCount

In output, valore che indica il numero corrente di voci eliminate dalla tabella. Il chiamante deve passare nuovamente questo valore nella chiamata successiva a RtlEnumerateGenericTableLikeADirectory. Questo valore consente alla routine RtlEnumerateGenericTableLikeADirectory di determinare se le eliminazioni dalla tabella si sono verificate tra chiamate a RtlEnumerateGenericTableLikeADirectory. Se le eliminazioni si sono verificate, l'enumerazione riprende con la voce della tabella corrispondente ai dati nel buffer e non con la voce della tabella indicata da RestartKey. Se RestartKey è NULL, questo parametro non ha alcun effetto sull'enumerazione.

[in] Buffer

Espressione chiave che determina dove iniziare l'enumerazione, quando RestartKey è NULL. Il chiamante può passare una chiave salvata che corrisponde a una voce specifica nella tabella e l'enumerazione inizierà alla voce specificata dalla chiave salvata, se RestartKey è NULL e NextFlag è FALSE. Per restituire la chiave che segue immediatamente una chiave salvata, passare la chiave qui, impostare RestartKey su NULL e NextFlag su TRUE. Se la chiave salvata è stata eliminata, l'enumerazione inizierà con la chiave corrispondente successiva.

Valore restituito

La routine RtlEnumerateGenericTableLikeADirectory restituisce un puntatore a una struttura definita dall'utente associata all'elemento tabella successivo nell'enumerazione. Se non sono presenti altri nuovi elementi per restituire il valore restituito è NULL.

Commenti

La routine RtlEnumerateGenericTableLikeADirectory offre un mezzo sicuro per enumerare una tabella generica tra operazioni di inserimento ed eliminazione intermixed. A partire dal primo nome della chiave corrispondente, RtlEnumerateGenericTableLikeADirectory restituisce ogni nome nella tabella esattamente una volta, a meno che il nome non sia stato inserito o eliminato durante l'enumerazione. Quando un nome della chiave viene inserito o eliminato durante un'enumerazione (ad esempio tra le chiamate a RtlEnumerateGenericTableLikeADirectory) potrebbe o non essere incluso nell'enumerazione. Se tali nomi sono inclusi dipende dallo stato del nome quando RtlEnumerateGenericTableLikeADirectory elabora l'intervallo di directory in cui viene trovato il nome.

Esistono quattro routine che è possibile usare per enumerare una tabella generica:

Per impostazione predefinita, il sistema operativo usa alberi splay per implementare tabelle generiche, ma la routine RtlEnumerateGenericTableLikeADirectory funziona solo con alberi Adelson-Velsky/Landis (AVL). Per configurare le routine di tabella generiche per usare alberi AVL anziché alberi di riproduzione nel driver, inserire l'istruzione define seguente in un file di intestazione comune prima di includere Ntddk.h:

 #define RTL_USE_AVL_TABLES 0

Se RTL_USE_AVL_TABLES non è definito, è necessario usare il formato AVL delle routine di tabella generiche.

I chiamanti di RtlEnumerateGenericTableLikeADirectory devono essere eseguiti in IRQL <= APC_LEVEL se una delle condizioni seguenti contiene:

  • La memoria allocata dal chiamante in Table o in Buffer è paginabile.

  • Il chiamante fornito da MatchFunction contiene codice paginabile.

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Intestazione ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h)
Libreria NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL (vedere la sezione Osservazioni)

Vedi anche

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable