RtlEnumerateGenericTableLikeADirectory-Funktion (ntddk.h)
Die RtlEnumerateGenericTableLikeADirectory Routine gibt die Elemente einer generischen Tabelle (1:1) in Sortierreihenfolge 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 aufgezählt 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 Übereinstimmungsfunktion übergeben werden sollen.
[in] NextFlag
Wenn *RestartKey nicht NULL-ist, gibt der Wert TRUE an, dass die Enumeration ein Element überspringt. If FALSE the enumeration resumes where it left off in the previous call to RtlEnumerateGenericTableLikeADirectory. Wenn *RestartKeyNULL-ist, weist der Wert TRUERtlEnumerateGenericTableLikeADirectory an, den nächsten Eintrag in der Struktur nach dem Eintrag zurückzugeben, der den Daten in Bufferentspricht. Ein Wert von FALSE weist RtlEnumerateGenericTableLikeADirectory an, den Eintrag in der Struktur zurückzugeben, der den Daten in Bufferentspricht.
[in, out] RestartKey
Ein Wert, der bestimmt, wo die Enumeration generischer Tabellenelemente beginnen oder fortgesetzt werden soll. Wenn *RestartKeyNULL-ist, beginnt oder wird die Aufzählung an der Position fortgesetzt, die in Bufferbeschrieben wird. Wenn NULL-nicht, wird die Aufzählung von dem Punkt fortgesetzt, an dem RestartKey- angibt. Beim Zurückgeben enthält das RestartKey einen Wert, der die Stelle in der Struktur angibt, an der die Aufzählung unterbrochen wurde. Beim nächsten Aufruf von RtlEnumerateGenericTableLikeADirectory Aufrufer sollte derselbe Wert zurück übergeben, um RtlEnumerateGenericTableLikeADirectory, wo die Enumeration fortgesetzt werden soll, zurückgibt. Im folgenden Codebeispiel wird veranschaulicht, wie Dies geschieht:
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 aus der Struktur zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectorygelöscht wird, wird die Aufzählung von der Position in der Struktur fortgesetzt, die in Bufferbeschrieben wird, unabhängig vom Wert von *RestartKey.
[in, out] DeleteCount
Bei der Ausgabe gibt ein Wert, der die aktuelle Anzahl von Einträgen angibt, die aus der Tabelle gelöscht wurden. Der Aufrufer muss diesen Wert beim nächsten Aufruf an RtlEnumerateGenericTableLikeADirectorywieder übergeben. Dieser Wert hilft dem RtlEnumerateGenericTableLikeADirectory Routine zu bestimmen, ob Löschungen aus der Tabelle zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectoryaufgetreten sind. Wenn Löschvorgänge aufgetreten sind, wird die Aufzählung mit dem Tabelleneintrag fortgesetzt, der den Daten in Bufferentspricht, und nicht mit dem tabelleneintrag, der durch RestartKeyangegeben ist. Wenn *RestartKeyNULL-ist, hat dieser Parameter keine Auswirkung auf die Enumeration..
[in] Buffer
Ein Schlüsselausdruck, der bestimmt, wo die Aufzählung beginnen soll, wenn *RestartKeyNULL-ist. Der Aufrufer kann einen gespeicherten Schlüssel übergeben, der einem bestimmten Eintrag in der Tabelle entspricht, und die Enumeration beginnt mit dem durch den gespeicherten Schlüssel angegebenen Eintrag, vorausgesetzt, *RestartKey ist NULL- und NextFlag ist FALSE. Um den Schlüssel zurückzugeben, der unmittelbar auf einen gespeicherten Schlüssel folgt, übergeben Sie hier den Schlüssel, legen Sie *RestartKey auf NULL- fest und NextFlag auf TRUE. Wenn der gespeicherte Schlüssel gelöscht wurde, beginnt die Aufzählung mit dem nächsten übereinstimmenen 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 vorhanden sind, um den Rückgabewert zurückzugeben, ist NULL-.
Bemerkungen
Die RtlEnumerateGenericTableLikeADirectory Routine bietet ein sicheres Mittel zum Aufzählen einer generischen Tabelle über intermixierte 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 während einer Aufzählung ein Schlüsselname eingefügt oder gelöscht wird (d. h. zwischen Aufrufen von RtlEnumerateGenericTableLikeADirectory), 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 aufzählen können:
Standardmäßig verwendet das Betriebssystem Splay-Strukturen, um generische Tabellen zu implementieren, aber die RtlEnumerateGenericTableLikeADirectory Routine funktioniert nur mit Adelson-Velsky/Landis (AVL)-Strukturen. Um die generischen Tabellenroutinen für die Verwendung von AVL-Strukturen anstelle von Splay-Strukturen in Ihrem Treiber zu konfigurieren, fügen Sie die folgende Define-Anweisung in eine allgemeine Headerdatei ein, bevor Ntddk.h eingeschlossen wird:
#define RTL_USE_AVL_TABLES 0
Wenn RTL_USE_AVL_TABLES nicht definiert ist, müssen Sie die AVL-Form der generischen Tabellenroutinen verwenden.
Anrufer von RtlEnumerateGenericTableLikeADirectory müssen bei IRQL <= APC_LEVEL ausgeführt werden, wenn eine der folgenden Bedingungen gilt:
Der vom Aufrufer zugewiesene Speicher in Table oder bei Buffer kann ausgelagert werden.
Der vom Aufrufer bereitgestellte MatchFunction- enthält ausgelagerten Code.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | <= APC_LEVEL (Siehe Abschnitt "Hinweise") |