FltQueryDirectoryFileEx-Funktion (fltkernel.h)

Artikel
02/26/2024

FltQueryDirectoryFileEx gibt verschiedene Arten von Informationen zu Dateien in dem von einem bestimmten Dateiobjekt angegebenen Verzeichnis zurück.

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 den Minifiltertreiber instance, der diese E/A initiiert.

FileObject

Zeiger auf das Dateiobjekt, das das abgefragte Verzeichnis darstellt.

FileInformation

Zeiger 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 Bytes, auf den von FileInformation verwiesen wird. Der Aufrufer sollte diesen Parameter entsprechend der angegebenen FileInformationClass festlegen.

FileInformationClass

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

QueryFlags

Mindestens eines 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 Flag festgelegt ist, beginnt der Scan mit dem ersten Eintrag im Verzeichnis. Wenn dieses Flag nicht festgelegt ist, wird der Scan an 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 gepackt, 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 Flag festgelegt ist, sollte der Scan an einer angegebenen indizierten Position im Verzeichnis beginnen. Dieses Flag kann nur festgelegt werden, wenn Sie Ihre eigene IRP_MJ_DIRECTORY_CONTROL IRP generieren. der Index wird im IRP angegeben. Wie die Position angegeben wird, variiert von Dateisystem zu Dateisystem.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Wenn dieses Flag festgelegt ist, sollten alle Dateisystemfilter, die die Verzeichnisvirtualisierung oder just-in-time-Erweiterung durchführen, die Anforderung einfach an das Dateisystem übergeben und Einträge zurückgeben, die sich derzeit auf dem Datenträger befinden. Dieses Flag wird nicht von allen Dateisystemen unterstützt.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Dateisysteme verwalten Dateicursorinformationen pro FileObject.FileObject-Verzeichniscursorinformationen . Wenn mehrere Threads Abfragen mit demselben FileObject ausführen, erfolgt der Zugriff auf die Pro-FileObject-Struktur über einen einzelnen Thread, um eine Beschädigung des Cursorzustands zu verhindern. Dieses Flag weist das Dateisystem an, keine FileObject-Cursorzustandsinformationen zu aktualisieren, sodass mehrere Threads mit demselben Handle gleichzeitig abfragen können. Er verhält sich so, als ob bei jedem Aufruf SL_RESTART_SCAN angegeben wird. Wenn beim nächsten Aufruf ein wilder Karte-Muster angegeben wird, wird der Vorgang nicht an der Stelle weitergegriffen, an der die letzte Abfrage beendet wurde. Dies ermöglicht eine echte Unterstützung für asynchrone Verzeichnisabfragen. Wenn dieses Flag in einer TxF-Transaktion verwendet wird, tritt ein Fehler auf. Dieses Flag wird nicht von allen Dateisystemen unterstützt.

FileName

Zeiger auf eine vom Aufrufer zugewiesene UNICODE_STRING-Struktur mit der Unicode-Zeichenfolge, die den Namen einer Datei (oder mehrerer Dateien, wenn Feldhalter verwendet werden) innerhalb des von FileObject angegebenen Verzeichnisses enthält. Dieser Parameter ist optional und kann NULL sein. Wenn fileNameNULL ist, sind alle Dateien enthalten.

Wenn FileName nicht NULL ist, werden nur Dateien, deren Namen mit der FileName-Zeichenfolge übereinstimmen, in die Verzeichnisüberprüfung einbezogen. Wenn das Flag "QueryFlagsResetScan " festgelegt ist, wird der Wert von 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 Fehlern status Werten, die zurückgegeben werden können, ist dateisystemspezifisch.

Hinweise

FltQueryDirectoryFileEx gibt Informationen zu Dateien zurück, die in dem durch FileObject dargestellten Verzeichnis enthalten sind.

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

Unter der Annahme, dass mindestens ein übereinstimmender Verzeichniseintrag gefunden wird, ist die Anzahl der Einträge, für die Informationen zurückgegeben werden, die kleinste der folgenden:

Ein Eintrag, wenn das SL_RETURN_SINGLE_ENTRY-Flag in QueryFlags festgelegt ist und FileNameNULL ist.
Die Anzahl der Einträge, die mit der FileName-Zeichenfolge übereinstimmen, wenn FileName nicht NULL ist. (Beachten Sie, dass es höchstens einen übereinstimmenden Eintrag geben kann, wenn die Zeichenfolge keine Feldhalter enthält.)
Die Anzahl der Einträge, deren Informationen in den Puffer passen, auf den FileInformation verweist.
Die Anzahl der im Verzeichnis enthaltenen Einträge.

Wenn beim ersten Aufruf von FltQueryDirectoryFileEx die für den ersten gefundenen Eintrag erstellte Struktur zu groß ist, um in den Ausgabepuffer zu passen, 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 aufzunehmen (nur beim ersten Aufruf und nicht bei nachfolgenden Aufrufen). In diesem Fall gibt FltQueryDirectoryFileEx den status Wert STATUS_BUFFER_OVERFLOW zurück. Wenn auch beim ersten Aufruf von FltQueryDirectoryFileEx keine Datei im FileObject-Verzeichnis vorhanden ist, die dem FileName-Parameter entspricht, gibt FltQueryDirectoryFileEx STATUS_NO_SUCH_FILE zurück.

Bei jedem Aufruf gibt FltQueryDirectoryFileEx so viele FILE_XXX_INFORMATION-Strukturen (eine pro Verzeichniseintrag) zurück, wie sie vollständig im Puffer enthalten sein können, auf den fileInformation verweist. Solange der Ausgabepuffer mindestens eine vollständige Struktur enthält, wird der zurückgegebene status Wert STATUS_SUCCESS. Es werden keine Informationen über verbleibende Einträge gemeldet. Mit Ausnahme der oben aufgeführten Fälle, in denen nur ein Eintrag zurückgegeben wird, muss FltQueryDirectoryFileEx also mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzulisten (z. B. wenn der FileName-Parameter mindestens ein Feldhalterzeichen enthält oder NULL ist).

Der letzte Aufruf von FltQueryDirectoryFileEx gibt einen leeren Ausgabepuffer zurück und meldet einen fehlerfreien status Wert 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 FltQueryDirectoryFileEx behoben ist. In nachfolgenden Aufrufen setzt FltQueryDirectoryFileEx die Verzeichnisüberprüfung überall dort fort, wo sie in derselben Enumeration aufgehört hat. Zwischen Aufrufen von FltQueryDirectoryFileEx können sich die tatsächlichen Verzeichniseinträge jedoch ändern, sodass sie nicht mehr mit der ursprünglichen Enumeration synchronisiert werden.

FltQueryDirectoryFileEx gibt null in jedem 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.