FltQueryDirectoryFile-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltQueryDirectoryFile-Routine gibt verschiedene Arten von Informationen zu Dateien in dem Verzeichnis zurück, das von einem bestimmten Dateiobjekt angegeben wird. Verwenden Sie FltQueryDirectoryFileEx für eine bessere Abfragesteuerung.

Syntax

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Parameter

[in] Instance

Undurchsichtiger Zeiger auf den Filtertreiber instance, der die E/A initiiert.

[in] FileObject

Zeiger auf das Dateiobjekt, das das zu scannende Verzeichnis darstellt.

[out] 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.

[in] Length

Größe des Puffers in Byte, auf den fileInformation verweist. Der Aufrufer sollte diesen Parameter entsprechend der angegebenen FileInformationClass festlegen.

[in] FileInformationClass

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

[in] ReturnSingleEntry

Legen Sie auf TRUE fest, wenn nur ein einzelner Eintrag zurückgegeben werden soll, andernfalls FALSE . Wenn dieser Parameter TRUE ist, gibt FltQueryDirectoryFile nur den ersten gefundenen Eintrag zurück.

[in, optional] FileName

Zeiger auf eine vom Aufrufer zugeordnete Unicode-Zeichenfolge, die den Namen einer Datei (oder mehrerer Dateien, wenn Wildcards verwendet werden) innerhalb des durch FileObject angegebenen Verzeichnisses enthält. Dieser Parameter ist optional und kann NULL sein.

Wenn FileName nicht NULL ist, werden nur Dateien, deren Namen mit der FileName-Zeichenfolge übereinstimmen, in die Verzeichnisüberprüfung einbezogen. Wenn FileNameNULL ist, werden alle Dateien eingeschlossen. Wenn RestartScanauf FALSE festgelegt ist, wird der Wert von FileName ignoriert.

[in] RestartScan

Legen Sie diesen Wert auf TRUE fest, wenn die Überprüfung am ersten Eintrag im Verzeichnis gestartet werden soll. Legen Sie auf FALSE fest, wenn die Überprüfung aus einem vorherigen Aufruf fortgesetzt wird. Der Aufrufer muss diesen Parameter beim ersten Aufruf von FltQueryDirectoryFile auf TRUE festlegen.

[out, optional] LengthReturned

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

Rückgabewert

FltQueryDirectoryFile gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Beachten Sie, dass der Satz von Fehler status Werten, die zurückgegeben werden können, dateisystemspezifisch ist.

Hinweise

FltQueryDirectoryFile gibt Informationen zu Dateien zurück, die in dem Verzeichnis enthalten sind, das durch FileObject dargestellt wird.

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

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

Ein Eintrag, wenn ReturnSingleEntryden Wert TRUE und FileNameden Wert NULL aufweist.
Die Anzahl der Einträge, die der FileName-Zeichenfolge entsprechen, wenn FileName nicht NULL ist. (Beachten Sie, dass, wenn die Zeichenfolge keine Wildcards enthält, höchstens ein übereinstimmender Eintrag vorhanden sein kann.)
Die Anzahl der Einträge, deren Informationen in den angegebenen Puffer passen.
Die Anzahl der im Verzeichnis enthaltenen Einträge.

Wenn beim ersten Aufruf von FltQueryDirectoryFile die für den ersten Eintrag erstellte Struktur zu groß war, 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 . Beim ersten Aufruf, aber nicht bei nachfolgenden, stellt das E/A-System sicher, dass der Puffer groß genug ist, um den festen Teil der entsprechenden FILE_XXX_INFORMATION-Struktur zu halten. In diesem Fall gibt FltQueryDirectoryFile einen geeigneten status Wert zurück, z. B. STATUS_BUFFER_OVERFLOW. Wenn auch beim ersten Aufruf von FltQueryDirectoryFile keine Datei im FileObject-Verzeichnis vorhanden ist, die dem FileName-Parameter entspricht, gibt FltQueryDirectoryFile einen geeigneten status Wert zurück, z. B. STATUS_NO_SUCH_FILE.

Bei jedem Aufruf gibt FltQueryDirectoryFile 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 wert status STATUS_SUCCESS. Es werden keine Informationen zu verbleibenden Einträgen gemeldet. Daher muss FltQueryDirectoryFile mit Ausnahme der oben aufgeführten Fälle, in denen nur ein Eintrag zurückgegeben wird, mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzulisten (z. B. wenn der FileName-Parameter ein oder mehrere Wildcardzeichen enthält oder NULL ist).

Der letzte Aufruf von FltQueryDirectoryFile gibt einen leeren Ausgabepuffer zurück und meldet einen geeigneten status Wert, z. B. STATUS_NO_MORE_FILES.

Hinweis

Wenn FltQueryDirectoryFile 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 FltQueryDirectoryFile festgelegt wurde. Bei nachfolgenden Aufrufen setzt FltQueryDirectoryFile die Verzeichnisüberprüfung überall dort fort, wo sie in derselben Enumeration aufgehört hat. Zwischen Aufrufen von FltQueryDirectoryFile können sich die tatsächlichen Verzeichniseinträge jedoch ändern, sodass sie nicht mehr mit der ursprünglichen Enumeration synchronisiert sind.

FltQueryDirectoryFile gibt null in jedem Element einer FILE_XXX_INFORMATION-Struktur zurück, die vom Dateisystem nicht unterstützt wird.

Informationen zu anderen Dateiinformationsabfrageroutinen finden Sie unter Dateiobjekte.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
Header	fltkernel.h (fltkernel.h einschließen)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")