RtlEnumerateGenericTableLikeADirectory-Funktion (ntddk.h)

  • Artikel

Die RtlEnumerateGenericTableLikeADirectory-Routine gibt die Elemente einer generischen Tabelle nacheinander in Sortierungsreihenfolge zurück.

Syntax

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

Parameter

[in] Table

Ein Zeiger auf die Tabelle Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE), die aufgelistet wird.

[in, optional] MatchFunction

Eine Übereinstimmungsfunktion, die bestimmt, welche Einträge zurückgegeben werden sollen. Wenn nicht angegeben, werden alle Knoten zurückgegeben.

[in, optional] MatchData

Die Daten, die an die Match-Funktion übergeben werden sollen.

[in] NextFlag

Wenn RestartKey nicht NULL ist, gibt der Wert TRUE an, dass die Enumeration ein Element überspringt. Bei FALSE wird die Enumeration dort fortgesetzt, wo sie im vorherigen Aufruf von RtlEnumerateGenericTableLikeADirectory aufgehört hat. Wenn RestartKeyNULL ist, weist der Wert TRUERtlEnumerateGenericTableLikeADirectory an, den nächsten Eintrag in der Struktur nach dem Eintrag zurückzugeben, der den Daten in Buffer entspricht. Der Wert FALSE weist RtlEnumerateGenericTableLikeADirectory an, den Eintrag in der Struktur zurückzugeben, der den Daten in Buffer entspricht.

[in, out] RestartKey

Ein -Wert, der bestimmt, wo die Enumeration generischer Tabellenelemente beginnen oder fortgesetzt werden soll. Wenn RestartKeyNULL ist, beginnt oder wird die Enumeration von der position aus fortgesetzt, die unter Puffer beschrieben wird. Wenn nicht NULL, wird die Enumeration ab dem Zeitpunkt fortgesetzt, an dem RestartKey angibt. Bei der Rückgabe enthält RestartKey einen Wert, der die Stelle in der Struktur angibt, an der die Enumeration aufgehört hat. Beim nächsten Aufruf von RtlEnumerateGenericTableLikeADirectory-Aufrufer sollte derselbe Wert zurückgegeben werden, um RtlEnumerateGenericTableLikeADirectory mitzuteilen, wo die Enumeration fortgesetzt werden soll. Im folgenden Codebeispiel wird dies veranschaulicht:

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.
}

Wenn ein Knoten zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectory aus der Struktur gelöscht wird, wird die Enumeration von der Position in der Struktur fortgesetzt, die unter Puffer beschrieben wird, unabhängig vom Wert von RestartKey.

[in, out] DeleteCount

In der Ausgabe ein Wert, der die aktuelle Anzahl der aus der Tabelle gelöschten Einträge angibt. Der Aufrufer muss diesen Wert beim nächsten Aufruf von RtlEnumerateGenericTableLikeADirectory wieder übergeben. Dieser Wert hilft der RtlEnumerateGenericTableLikeADirectory-Routine zu ermitteln, ob zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectory Löschungen aus der Tabelle vorgenommen wurden. Wenn Löschungen vorgenommen wurden, wird die Enumeration mit dem Tabelleneintrag fortgesetzt, der den Daten in Buffer entspricht, und nicht mit dem tabelleneintrag, der durch RestartKey angegeben wird. Wenn RestartKeyNULL ist, hat dieser Parameter keine Auswirkungen auf die Enumeration.

[in] Buffer

Ein Schlüsselausdruck, der bestimmt, wo die Enumeration beginnen soll, wenn RestartKeyNULL ist. Der Aufrufer kann einen gespeicherten Schlüssel übergeben, der mit einem bestimmten Eintrag in der Tabelle übereinstimmt, und die Enumeration beginnt bei dem eintrag, der durch den gespeicherten Schlüssel angegeben wird, vorausgesetzt RestartKey ist NULL und NextFlag ist FALSE. Um den Schlüssel zurückzugeben, der unmittelbar auf einen gespeicherten Schlüssel folgt, übergeben Sie den Schlüssel hier, legen Sie RestartKey auf NULL und NextFlag auf TRUE fest. Wenn der gespeicherte Schlüssel gelöscht wurde, beginnt die Enumeration mit dem nächsten übereinstimmenden Schlüssel.

Rückgabewert

Die RtlEnumerateGenericTableLikeADirectory-Routine gibt einen Zeiger auf eine benutzerdefinierte Struktur zurück, die dem nächsten Tabellenelement in der Enumeration zugeordnet ist. Wenn keine neuen Elemente mehr zum Zurückgeben vorhanden sind, ist der Rückgabewert NULL.

Hinweise

Die RtlEnumerateGenericTableLikeADirectory-Routine bietet ein sicheres Mittel zum Aufzählen einer generischen Tabelle über gemischte Einfüge- und Löschvorgänge hinweg. Beginnend mit dem ersten übereinstimmenden Schlüsselnamen gibt RtlEnumerateGenericTableLikeADirectory jeden Namen in der Tabelle genau einmal zurück, es sei denn, der Name wurde während der Enumeration eingefügt oder gelöscht. Wenn ein Schlüsselname während einer Enumeration (d. h. zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectory) eingefügt oder gelöscht wird, kann er in der Enumeration enthalten sein oder nicht. Ob solche Namen enthalten sind, hängt vom Status des Namens ab, wenn RtlEnumerateGenericTableLikeADirectory den Verzeichnisbereich verarbeitet, in dem der Name gefunden wird.

Es gibt vier Routinen, mit denen Sie eine generische Tabelle auflisten können:

Standardmäßig verwendet das Betriebssystem Splaybaumstrukturen, um generische Tabellen zu implementieren, aber die RtlEnumerateGenericTableLikeADirectory-Routine funktioniert nur mit Adelson-Velsky/Landis-Strukturen (AVL). Um die generischen Tabellenroutinen so zu konfigurieren, dass sie AVL-Strukturen anstelle von Splaystrukturen in Ihrem Treiber verwenden, fügen Sie die folgende define-Anweisung in eine allgemeine Headerdatei ein, bevor Sie Ntddk.h einschließen:

 #define RTL_USE_AVL_TABLES 0

Wenn RTL_USE_AVL_TABLES nicht definiert ist, müssen Sie die AVL-Form der generischen Tabellenroutinen verwenden.

Aufrufer von RtlEnumerateGenericTableLikeADirectory müssen unter IRQL <= APC_LEVEL ausgeführt werden, wenn eine der folgenden Bedingungen erfüllt ist:

  • Der vom Aufrufer zugeordnete Arbeitsspeicher bei Table oder buffer kann ausgelagert werden.

  • Die vom Aufrufer bereitgestellte MatchFunction enthält ausgelagerten Code.

Anforderungen

Anforderung Wert
Zielplattform Universell
Header ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL (siehe Abschnitt "Hinweise")

Weitere Informationen

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutsplaying

RtlGetElementGenericTable