FltQueryDirectoryFileEx-Funktion (fltkernel.h)

Artikel
07/16/2024

FltQueryDirectoryFileEx gibt verschiedene Arten von Informationen zu Dateien im verzeichnis zurück, das durch ein bestimmtes Dateiobjekt angegeben wird.

Syntax

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Parameter

Instance

Undurchsichtiger Zeiger auf die Minifiltertreiberinstanz, die diese E/A initiiert.

FileObject

Zeigen Sie auf das Dateiobjekt, das das abgefragte Verzeichnis darstellt.

FileInformation

Zeigen Sie auf einen Puffer, der die gewünschten Informationen zur Datei empfängt. Die Struktur der im Puffer zurückgegebenen Informationen wird durch den parameter FileInformationClass definiert.

Length

Größe des Puffers in Byte, auf den FileInformationverweist. Der Aufrufer sollte diesen Parameter gemäß der angegebenen FileInformationClassfestlegen.

FileInformationClass

Typ der Informationen, die über Dateien im Verzeichnis zurückgegeben werden sollen. Die Liste der möglichen Werte finden Sie im FileInformationClass Parameter von NtQueryDirectoryFileEx.

QueryFlags

Mindestens eine der Flags, die in SL_QUERY_DIRECTORY_MASK enthalten sind. Mögliche Werte werden in der folgenden Tabelle angegeben.

Wert	Bedeutung
SL_RESTART_SCAN (0x00000001)	Wenn dieses Kennzeichen festgelegt ist, beginnt die Überprüfung beim ersten Eintrag im Verzeichnis. Wenn diese Kennzeichnung nicht festgelegt ist, wird die Überprüfung von dem Ort fortgesetzt, an dem die letzte Abfrage beendet wurde.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Normalerweise ist der Rückgabepuffer mit so vielen übereinstimmenden Verzeichniseinträgen verpackt, die passen. Wenn dieses Flag festgelegt ist, gibt das Dateisystem jeweils nur einen Verzeichniseintrag zurück. Dadurch wird der Vorgang weniger effizient.
SL_INDEX_SPECIFIED (0x00000004)	Wenn dieses Kennzeichen festgelegt ist, sollte die Überprüfung an einer angegebenen indizierten Position im Verzeichnis beginnen. Dieses Kennzeichen kann nur festgelegt werden, wenn Sie ihre eigene IRP_MJ_DIRECTORY_CONTROL IRP-generieren; der Index wird im IRP angegeben. Die Angabe der Position variiert von Dateisystem zu Dateisystem.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Wenn dieses Kennzeichen festgelegt ist, sollten alle Dateisystemfilter, die Verzeichnisvirtualisierung oder Just-in-Time-Erweiterung durchführen, einfach die Anforderung an das Dateisystem übergeben und Einträge zurückgeben, die sich derzeit auf dem Datenträger befinden. Nicht alle Dateisysteme unterstützen dieses Flag.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Dateisysteme verwaltenFileObject Verzeichniscursorinformationen. Wenn mehrere Threads Abfragen mit demselben FileObject-ausführen, wird der Zugriff auf dieFileObject- Struktur einzelner Threads ausgeführt, um Beschädigungen des Cursorzustands zu verhindern. Dieses Flag weist das Dateisystem an,FileObject Cursorstatusinformationen nicht zu aktualisieren, sodass mehrere Threads parallel mit demselben Handle abgefragt werden können. Es verhält sich so, als ob SL_RESTART_SCAN für jeden Anruf angegeben wird. Wenn beim nächsten Aufruf ein Wildcardmuster angegeben wird, wird der Vorgang nicht an der Stelle aufgenommen, an der die letzte Abfrage beendet wurde. Dies ermöglicht die asynchrone Unterstützung von Verzeichnisabfragen. Wenn dieses Flag in einer TxF-Transaktion verwendet wird, schlägt der Vorgang fehl. Nicht alle Dateisysteme unterstützen dieses Flag.

FileName

Zeiger auf eine vom Aufrufer zugewiesene UNICODE_STRING Struktur mit der Unicode-Zeichenfolge, die den Namen einer Datei (oder mehrerer Dateien, wenn Wildcards verwendet werden) innerhalb des durch FileObjectangegebenen Verzeichnis enthält. Dieser Parameter ist optional und kann NULL-werden. Wenn fileName-NULL-ist, werden alle Dateien eingeschlossen.

Wenn FileName- nicht NULL-ist, werden nur Dateien, deren Namen der FileName- Zeichenfolge entsprechen, in die Verzeichnisüberprüfung einbezogen. Wenn die QueryFlagsResetScan Flag festgelegt ist, wird der Wert FileName ignoriert.

LengthReturned

Empfängt die Anzahl der Bytes, die tatsächlich in den angegebenen FileInformation Puffer geschrieben wurden.

Rückgabewert

FltQueryDirectoryFileEx gibt STATUS_SUCCESS oder einen entsprechenden Fehlercode zurück. Der Satz von Fehlerstatuswerten, die zurückgegeben werden können, ist dateisystemspezifisch.

Bemerkungen

FltQueryDirectoryFileEx Gibt Informationen zu Dateien zurück, die im Verzeichnis enthalten sind, das durch FileObjectdargestellt wird.

Der erste Aufruf von FltQueryDirectoryFileEx bestimmt, welche Einträge in die Verzeichnisüberprüfung für alle nachfolgenden Aufrufe aufgenommen werden sollen, basierend auf den Werten QueryFlags und FileName. Wenn mindestens ein übereinstimmender Eintrag vorhanden ist, erstellt FltQueryDirectoryFileEx für jeden Eintrag eine FILE_XXX-_INFORMATION-Struktur (siehe obige Tabelle) und speichert die Struktur im Puffer.

Wenn angenommen wird, dass mindestens ein übereinstimmener Verzeichniseintrag gefunden wird, ist die Anzahl der Einträge, für die Informationen zurückgegeben werden, die kleinste der folgenden Werte sind:

Ein Eintrag, wenn das SL_RETURN_SINGLE_ENTRY-Flag in QueryFlags- festgelegt ist und FileName-NULL-ist.
Die Anzahl der Einträge, die der FileName- Zeichenfolge entsprechen, wenn FileName- nicht NULL-ist. (Wenn die Zeichenfolge keine Wildcards enthält, kann es höchstens einen übereinstimmenden Eintrag geben.)
Die Anzahl der Einträge, deren Informationen in den Puffer passen, auf den FileInformationverweist.
Die Anzahl der Einträge im Verzeichnis.

Wenn beim ersten Aufruf von FltQueryDirectoryFileExdie für den ersten gefundenen Eintrag erstellte Struktur zu groß ist, um in den Ausgabepuffer einzupassen, wird nur der feste Teil der Struktur zurückgegeben. Der feste Teil besteht aus allen Feldern der Struktur mit Ausnahme der endgültigen FileName- Zeichenfolge. Das E/A-Subsystem stellt sicher, dass der Puffer groß genug ist, um den festen Teil der entsprechenden FILE_XXX-_INFORMATION Struktur (nur für den ersten Aufruf und nicht für nachfolgende Aufrufe) zu halten. In diesem Fall gibt FltQueryDirectoryFileEx einen Statuswert von STATUS_BUFFER_OVERFLOW zurück. Wenn beim ersten Aufruf von FltQueryDirectoryFileExkeine Datei im Verzeichnis FileObject vorhanden ist, das dem parameter FileName entspricht, gibt FltQueryDirectoryFileEx STATUS_NO_SUCH_FILE zurück.

Bei jedem Aufruf gibt FltQueryDirectoryFileEx so viele FILE_XXX-_INFORMATION-Strukturen (eins pro Verzeichniseintrag) zurück, wie sie vollständig im Puffer enthalten sein können, auf den FileInformationverweist. Solange der Ausgabepuffer mindestens eine vollständige Struktur enthält, wird der zurückgegebene Statuswert STATUS_SUCCESS. Es werden keine Informationen zu verbleibenden Einträgen gemeldet. Mit Ausnahme der oben aufgeführten Fälle, in denen nur ein Eintrag zurückgegeben wird, muss FltQueryDirectoryFileEx- mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzählen zu können (z. B. wenn der FileName Parameter ein oder mehrere Wildcardzeichen enthält oder NULList).

Der letzte Aufruf von FltQueryDirectoryFileEx gibt einen leeren Ausgabepuffer zurück und meldet einen Nichtfehlerstatuswert von STATUS_NO_MORE_FILES.

Hinweis: Wenn FltQueryDirectoryFileEx mehrmals im selben Verzeichnis aufgerufen wird, ist es möglich, dass die Anzahl der Einträge, für die Informationen zurückgegeben werden, kleiner als erwartet ist. Dies liegt daran, dass der Satz von Einträgen, die in die Verzeichnisüberprüfung einbezogen werden sollen, beim ersten Aufruf von FltQueryDirectoryFileExbehoben ist. In nachfolgenden Aufrufen setzt FltQueryDirectoryFileEx den Verzeichnisscan an der Stelle fort, an der sie in dieser Enumeration aufgehört hat. Zwischen Aufrufen von FltQueryDirectoryFileExkönnen sich die tatsächlichen Verzeichniseinträge jedoch ändern, sodass sie nicht mehr mit der ursprünglichen Enumeration synchronisiert werden.

FltQueryDirectoryFileEx gibt null in einem Element einer FILE_XXX-_INFORMATION-Struktur zurück, die vom Dateisystem nicht unterstützt wird.

Aufrufer von FltQueryDirectoryFileEx- müssen unter IRQL = PASSIVE_LEVEL und mit aktivierten APCs ausgeführt werden. Weitere Informationen finden Sie unter Deaktivieren von APCs.