NtQueryDirectoryFileEx-Funktion (ntifs.h)

Artikel
08/07/2023

Die NtQueryDirectoryFileEx-Routine gibt verschiedene Arten von Informationen zu Dateien in dem verzeichnis zurück, das durch ein bestimmtes Dateihandle angegeben wird.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Parameter

[in] FileHandle

Ein von NtCreateFile oder NtOpenFile zurückgegebenes Handle für das Dateiobjekt, das das Verzeichnis darstellt, für das Informationen angefordert werden. Das Dateiobjekt muss für asynchrone E/A geöffnet worden sein, wenn der Aufrufer einen Nicht-NULL-Wert für Event oder ApcRoutine angibt.

[in, optional] Event

Ein optionales Handle für ein vom Anrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der angeforderte Vorgang abgeschlossen ist und das angegebene Ereignis auf den Signalzustand festgelegt ist. Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn der Aufrufer wartet, bis fileHandle auf den Signalzustand festgelegt wird.

[in, optional] ApcRoutine

Eine Adresse einer optionalen, vom Anrufer bereitgestellten APC-Routine, die aufgerufen werden soll, wenn der angeforderte Vorgang abgeschlossen ist. Dieser Parameter ist optional und kann NULL sein. Wenn dem Dateiobjekt ein E/A-Vervollständigungsobjekt zugeordnet ist, muss dieser Parameter NULL sein.

[in, optional] ApcContext

Ein optionaler Zeiger auf einen vom Aufrufer bestimmten Kontextbereich, wenn der Aufrufer einen APC bereitstellt oder wenn dem Dateiobjekt ein E/A-Vervollständigungsobjekt zugeordnet ist. Wenn der Vorgang abgeschlossen ist, wird dieser Kontext an den APC übergeben, sofern einer angegeben wurde, oder als Teil der Vervollständigungsmeldung, die der E/A-Manager an das zugehörige E/A-Vervollständigungsobjekt sendet.

Dieser Parameter ist optional und kann NULL sein. Es muss NULL sein, wenn ApcRoutine NULL ist und dem Dateiobjekt kein E/A-Vervollständigungsobjekt zugeordnet ist.

[out] IoStatusBlock

Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der Bytes, die in den FileInformation-Puffer geschrieben wurden, im Element Information der Struktur zurückgegeben.

[out] FileInformation

Ein Zeiger auf einen Ausgabepuffer, 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

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

FileInformationClass

Der Typ der Informationen, die zu Dateien im Verzeichnis zurückgegeben werden sollen. Typ der Informationen, die zu Dateien im Verzeichnis zurückgegeben werden sollen. FileInformationClass kann einer der folgenden FILE_INFORMATION_CLASS Werte sein.

Wert	Bedeutung
FileDirectoryInformation (1)	Gibt eine FILE_DIRECTORY_INFORMATION-Struktur für jede Datei zurück.
FileFullDirectoryInformation (2)	Gibt eine FILE_FULL_DIR_INFORMATION-Struktur für jede Datei zurück.
FileBothDirectoryInformation (3)	Gibt eine FILE_BOTH_DIR_INFORMATION-Struktur für jede Datei zurück.
FileNamesInformation (12)	Gibt eine FILE_NAMES_INFORMATION-Struktur für jede Datei zurück.
FileObjectIdInformation (29)	Gibt eine FILE_OBJECTID_INFORMATION-Struktur für jede Datei zurück, die über eine Objekt-ID auf dem Volume verfügt. Diese Informationsklasse ist nur für das spezielle Verzeichnis "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" auf NTFS-Volumes gültig.
FileQuotaInformation (32)	Gibt eine einzelne FILE_QUOTA_INFORMATION-Struktur für jeden Benutzer auf dem Volume zurück, für das Kontingente angewendet wurden. Diese Informationsklasse ist nur für das spezielle Verzeichnis "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" auf NTFS-Volumes gültig.
FileReparsePointInformation (33)	Gibt eine einzelne FILE_REPARSE_POINT_INFORMATION-Struktur für jede Datei zurück, die über einen Analysepunkt auf dem Volume verfügt. Diese Informationsklasse ist nur für das spezielle Verzeichnis "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" auf NTFS- und ReFS-Volumes gültig.
FileIdBothDirectoryInformation (37)	Gibt eine FILE_ID_BOTH_DIR_INFORMATION-Struktur für jede Datei zurück.
FileIdFullDirectoryInformation (38)	Gibt eine FILE_ID_FULL_DIR_INFORMATION-Struktur für jede Datei zurück.
FileIdGlobalTxDirectoryInformation (50)	Gibt eine FILE_ID_GLOBAL_TX_DIR_INFORMATION-Struktur für jede Datei zurück.
FileIdExtdDirectoryInformation (60)	Gibt eine FILE_ID_EXTD_DIR_INFORMATION-Struktur für jede Datei zurück.
FileIdExtdBothDirectoryInformation (63)	Gibt eine FILE_ID_EXTD_BOTH_DIR_INFORMATION-Struktur für jede Datei zurück.

[in] 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)	Der Scan beginnt 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)	Der Scan sollte 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)	Alle Dateisystemfilter, die Verzeichnisvirtualisierung oder Just-in-Time-Erweiterung durchführen, sollten 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.

[in, optional] FileName

Ein optionaler Zeiger auf eine vom Aufrufer zugewiesene Unicode-Zeichenfolge, die den Namen einer Datei (oder mehrerer Dateien, wenn Wildcards verwendet werden) innerhalb des von FileHandle angegebenen Verzeichnisses enthält. Dieser Parameter ist optional:

Wenn FileName nicht NULL ist, werden nur Dateien, deren Namen mit der FileName-Zeichenfolge übereinstimmen, in die Verzeichnisüberprüfung einbezogen.
Wenn FileName NULL ist:
- Wenn SL_RETURN_SINGLE_ENTRY in QueryFlags nicht festgelegt ist, sind alle Dateien enthalten.
- Wenn SL_RETURN_SINGLE_ENTRY festgelegt ist, ist nur eine Datei enthalten.

Der Dateiname wird als Suchausdruck verwendet und beim ersten Aufruf von NtQueryDirectoryFileEx für ein bestimmtes Handle erfasst. Nachfolgende Aufrufe von NtQueryDirectoryFileEx verwenden den Suchausdruck, der im ersten Aufruf festgelegt ist. Der FileName-Parameter , der an nachfolgende Aufrufe übergeben wird, wird ignoriert.

Rückgabewert

NtQueryDirectoryFileEx gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Der Satz von Fehlern status Werten, die zurückgegeben werden können, ist dateisystemspezifisch. NtQueryDirectoryFileEx gibt auch die Anzahl der Bytes zurück, die tatsächlich in den angegebenen FileInformation-Puffer im Informationselement von IoStatusBlock geschrieben wurden. Einige mögliche Fehlercodes und Gründe können die folgenden sein:

Rückgabecode	Bedeutung
STATUS_BUFFER_OVERFLOW	Der Ausgabepuffer ist nicht groß genug, um den vollständigen Dateinamen zurückzugeben.
STATUS_BUFFER_TOO_SMALL	Der Ausgabepuffer ist nicht groß genug für mindestens die von FileInformationClass identifizierte Basisstruktur.
STATUS_INVALID_INFO_CLASS	Eine ungültige FileInformationClass wurde angegeben, oder die Informationsklasse ist nur für eine spezielle Bedingung gültig (z. B. nur für ein spezielles Verzeichnis gültig).
STATUS_INVALID_PARAMETER	Einer der Parameter ist für das Dateisystem ungültig.

Hinweise

NtQueryDirectoryFileEx gibt Informationen zu Dateien zurück, die in dem von FileHandle dargestellten Verzeichnis enthalten sind.

Falls angegeben, bestimmt FileName die Einträge, die in der Verzeichnisüberprüfung für alle nachfolgenden Aufrufe von NtQueryDirectoryFileEx für eine bestimmte FileHandle enthalten sind.

Wenn mindestens ein übereinstimmende Eintrag vorhanden ist, erstellt NtQueryDirectoryFileEx eine FILE_XXX_INFORMATION-Struktur für jeden Eintrag und speichert sie 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 SL_RETURN_SINGLE_ENTRY in QueryFlags festgelegt ist und FileName NULL ist.
Die Anzahl der Einträge, die mit der FileName-Zeichenfolge übereinstimmen, wenn FileName nicht NULL ist. Wenn die Zeichenfolge keine Feldhalter 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 im Verzeichnis enthaltenen Einträge.

Wenn beim ersten Aufruf von NtQueryDirectoryFileEx die Struktur, die für den ersten gefundenen Eintrag erstellt wird, zu groß ist, um in den Ausgabepuffer zu passen, führt diese Routine folgendes aus:

Schreibt den festen Teil der Struktur in den Ausgabepuffer von FileInformation. Der feste Teil besteht aus allen Feldern mit Ausnahme der endgültigen FileName-Zeichenfolge . Beim ersten Aufruf, aber nicht bei nachfolgenden Aufrufen, stellt das E/A-System sicher, dass der Puffer groß genug ist, um den festen Teil der entsprechenden FILE_XXX_INFORMATION-Struktur aufzunehmen.
Schreibt in den Ausgabepuffer so viel von der FileName-Zeichenfolge , wie es passt.
Gibt einen entsprechenden status Wert wie STATUS_BUFFER_OVERFLOW zurück.

Bei jedem Aufruf gibt NtQueryDirectoryFileEx so viele FILE_XXX_INFORMATION-Strukturen (eine pro Verzeichniseintrag) zurück, die vollständig im Puffer enthalten sein können, auf den fileInformation verweist:

Beim ersten Aufruf gibt NtQueryDirectoryFileEx nur STATUS_SUCCESS zurück, wenn der Ausgabepuffer mindestens eine vollständige Struktur enthält.
Wenn der Ausgabepuffer bei nachfolgenden Aufrufen keine Strukturen enthält, gibt NtQueryDirectoryFileEx STATUS_SUCCESS zurück, legt jedoch IoStatusBlock-Information> = 0 fest, um den Aufrufer über diese Bedingung zu benachrichtigen. In diesem Fall sollte der Aufrufer einen größeren Puffer zuordnen und NtQueryDirectoryFileEx erneut aufrufen. 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 NtQueryDirectoryFileEx also mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzulisten.

Beim Aufrufen von NtQueryDirectoryFileEx werden möglicherweise Änderungen am Verzeichnis angezeigt, die parallel zu NtQueryDirectoryFileEx-Aufrufen vorgenommen werden. Dieses Verhalten ist von der Implementierung des zugrunde liegenden Dateisystems abhängig.

Der letzte Aufruf von NtQueryDirectoryFileEx gibt einen leeren Ausgabepuffer zurück und meldet einen entsprechenden status Wert wie STATUS_NO_MORE_FILES.

Wenn NtQueryDirectoryFileEx mehrmals im selben Verzeichnis aufgerufen wird und ein anderer Vorgang den Inhalt dieses Verzeichnisses ändert, können alle Änderungen angezeigt werden, abhängig vom Zeitpunkt der Vorgänge.

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

Aufrufer von NtQueryDirectoryFileEx müssen unter IRQL = PASSIVE_LEVEL und mit aktivierten speziellen Kernel-APCs ausgeführt werden.

Informationen zu anderen Dateiinformationsabfrageroutinen finden Sie unter Dateiobjekte.

Hinweis

Wenn der Aufruf der NtQueryDirectoryFileEx-Funktion im Kernelmodus erfolgt, sollten Sie den Namen "ZwQueryDirectoryFileEx" anstelle von "NtQueryDirectoryFileEx" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10, Version 1709
Kopfzeile	ntifs.h
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)