FltQueryDirectoryFile-Funktion (fltkernel.h)

Artikel
12/21/2024

Die FltQueryDirectoryFile Routine gibt verschiedene Arten von Informationen zu Dateien im Verzeichnis zurück, das durch ein bestimmtes Dateiobjekt angegeben ist. Verwenden Sie FltQueryDirectoryFileEx- für ein größeres Abfragesteuerelement.

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 die Filtertreiberinstanz, die die E/A initiiert.

[in] FileObject

Zeigen Sie auf das Dateiobjekt, das das zu scannende Verzeichnis darstellt.

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

[in] Length

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

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

[in] ReturnSingleEntry

Wird auf TRUE- festgelegt, wenn nur ein einzelner Eintrag zurückgegeben werden soll, FALSE andernfalls. Wenn dieser Parameter TRUEist, gibt FltQueryDirectoryFile nur den ersten gefundenen Eintrag zurück.

[in, optional] FileName

Zeigen Sie auf eine von einem Aufrufer zugewiesene 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- nicht NULL-ist, werden nur Dateien, deren Namen der FileName- Zeichenfolge entsprechen, in die Verzeichnisüberprüfung einbezogen. Wenn FileName-NULL-ist, werden alle Dateien eingeschlossen. Wenn RestartScanFALSEist, wird der Wert FileName ignoriert.

[in] RestartScan

Legen Sie diesen Wert auf TRUE fest,, wenn der Scan beim ersten Eintrag im Verzeichnis gestartet werden soll. Wird auf FALSE- festgelegt, wenn der Scan von einem vorherigen Aufruf fortgesetzt wird. Der Aufrufer muss diesen Parameter beim erstmaligen Aufrufen FltQueryDirectoryFile-auf TRUE festlegen.

[out, optional] LengthReturned

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

Rückgabewert

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

Bemerkungen

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

Der erste Aufruf von FltQueryDirectoryFile bestimmt, welche Einträge in die Verzeichnisüberprüfung für alle nachfolgenden Aufrufe aufgenommen werden sollen, basierend auf den Werten ReturnSingleEntry, FileNameund RestartScan. Wenn mindestens ein übereinstimmender Eintrag vorhanden ist, erstellt FltQueryDirectoryFile eine FILE_XXX-_INFORMATION-Struktur (siehe die obige Tabelle) für jeden Eintrag wiederum 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 ReturnSingleEntryTRUE 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 angegebenen Puffer passen.
Die Anzahl der Einträge im Verzeichnis.

Wenn beim ersten Aufruf von FltQueryDirectoryFiledie für den ersten Eintrag erstellte Struktur zu groß für den Ausgabepuffer gefunden wurde, 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. Im 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 Statuswert wie STATUS_BUFFER_OVERFLOW zurück. Wenn beim ersten Aufruf von FltQueryDirectoryFilekeine Datei im verzeichnis FileObject vorhanden ist, die dem parameter FileName entspricht, gibt FltQueryDirectoryFile einen entsprechenden Statuswert wie STATUS_NO_SUCH_FILE zurück.

Bei jedem Aufruf gibt FltQueryDirectoryFile 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 FltQueryDirectoryFile- mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzählen zu können (z. B. wenn der FileName Parameter mindestens ein Wildcardzeichen enthält oder NULList).

Der letzte Aufruf von FltQueryDirectoryFile gibt einen leeren Ausgabepuffer zurück und meldet einen geeigneten Statuswert wie STATUS_NO_MORE_FILES.

Anmerkung

Wenn FltQueryDirectoryFile mehrmals im selben Verzeichnis aufgerufen wird, ist es möglich, dass die Anzahl der zurückgegebenen Informationen 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 FltQueryDirectoryFilebehoben ist. In nachfolgenden Aufrufen setzt FltQueryDirectoryFile den Verzeichnisscan an der Stelle fort, an der sie in dieser Enumeration aufgehört hat. Zwischen Aufrufen von FltQueryDirectoryFilekönnen sich jedoch die tatsächlichen Verzeichniseinträge ändern, sodass sie nicht mehr mit der ursprünglichen Enumeration synchronisiert werden.

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

Informationen zu anderen Dateiinformationsabfrageroutinen finden Sie unter File Objects.

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
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Header-	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL-	Fltmgr.sys
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")