NtQueryDirectoryFile-Funktion (ntifs.h)

Artikel
08/07/2023

Die NtQueryDirectoryFile-Routine gibt verschiedene Arten von Informationen zu Dateien in dem Verzeichnis zurück, das von einem bestimmten Dateihandle angegeben wird.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
  [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,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           BOOLEAN                ReturnSingleEntry,
  [in, optional] PUNICODE_STRING        FileName,
  [in]           BOOLEAN                RestartScan
);

Parameter

[in] FileHandle

Ein Handle, das von NtCreateFile oder NtOpenFile für das Dateiobjekt zurückgegeben wird, 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 Wert ungleich NULL für Event oder ApcRoutine angibt.

[in, optional] Event

Ein optionales Handle für ein vom Aufrufer 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 wird. Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn der Aufrufer wartet, bis fileHandle auf den Signaled-Zustand festgelegt wird.

[in, optional] ApcRoutine

Eine Adresse einer optionalen, vom Aufrufer 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 Abschlussmeldung, die der E/A-Manager an das zugeordnete E/A-Vervollständigungsobjekt sendet.

Dieser Parameter ist optional und kann NULL sein. Er 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 den endgültigen Abschluss status und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl von Bytes, die in den FileInformation-Puffer geschrieben werden, im Information-Element der Struktur zurückgegeben.

[out] FileInformation

Ein 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

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

[in] 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. 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 NtQueryDirectoryFile nur den ersten gefundenen Eintrag zurück.

[in, optional] FileName

Ein optionaler Zeiger auf eine vom Aufrufer zugeordnete Unicode-Zeichenfolge, die den Namen einer Datei (oder mehrerer Dateien, wenn Wildcards verwendet werden) innerhalb des durch FileHandle 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 FileName NULL ist, werden alle Dateien eingeschlossen.

FileName wird als Suchausdruck verwendet und beim ersten Aufruf von NtQueryDirectoryFile für ein bestimmtes Handle erfasst. Nachfolgende Aufrufe von NtQueryDirectoryFile verwenden den Suchausdruck, der im ersten Aufruf festgelegt wurde. Der FileName-Parameter , der an nachfolgende Aufrufe übergeben wird, wird 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.

Wenn die NtQueryDirectoryFile-Routine für ein bestimmtes Handle aufgerufen wird, wird der RestartScan-Parameter unabhängig von seinem Wert so behandelt, als wäre er auf TRUE festgelegt. Bei nachfolgenden NtQueryDirectoryFile-Aufrufen wird der Wert des RestartScan-Parameters berücksichtigt.

Rückgabewert

Die NtQueryDirectoryFile-Routinegibt STATUS_SUCCESS oder einen geeigneten Fehler status zurück. Der Satz von Fehlern status Werten, die zurückgegeben werden können, ist dateisystemspezifisch. NtQueryDirectoryFilegibt auch die Anzahl der Bytes zurück, die tatsächlich in den angegebenen FileInformation-Puffer im Information-Member von IoStatusblock geschrieben wurden. Eine Liste mit einigen möglichen Fehlercodes finden Sie unter NtQueryDirectoryFileEx .

Hinweise

Die NtQueryDirectoryFile-Routine gibt Informationen zu Dateien zurück, die in dem durch FileHandle dargestellten Verzeichnis enthalten sind.

Wenn angegeben, bestimmt der Wert des FileName-Parameters die Einträge, die in der Verzeichnisüberprüfung für alle nachfolgenden Aufrufe von NtQueryDirectoryFile für ein bestimmtes FileHandle enthalten sind.

Wenn mindestens ein übereinstimmende Eintrag vorhanden ist, erstellt NtQueryDirectoryFile eine FILE_XXX_INFORMATION struktur für jeden Eintrag und speichert sie 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 Werte:

Ein Eintrag, wenn ReturnSingleEntryden Wert TRUE und FileName den 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 NtQueryDirectoryFile die für den ersten gefundenen Eintrag erstellte Struktur zu groß ist, um in den Ausgabepuffer zu passen, schreibt die Routine den festen Teil der Struktur in den Ausgabepuffer. Die Routine schreibt dann so viel aus der FileName-Zeichenfolge in den Ausgabepuffer, wie es passt. (Der feste Teil der Struktur besteht aus allen Feldern mit Ausnahme der endgültigen FileName-Zeichenfolge. Beim ersten Aufruf, jedoch 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 zu halten.) In diesem Fall gibt NtQueryDirectoryFile einen geeigneten status Wert zurück, z. B. STATUS_BUFFER_OVERFLOW.

Bei jedem Aufruf gibt NtQueryDirectoryFile so viele FILE_XXX_INFORMATION-Strukturen zurück (eine pro Verzeichniseintrag), wie sie vollständig im Puffer enthalten sein können, auf den FileInformation verweist. Beim ersten Aufruf gibt NtQueryDirectoryFile nur dann 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 NtQueryDirectoryFile STATUS_SUCCESS 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 NtQueryDirectoryFile erneut aufrufen. Es werden keine Informationen zu verbleibenden Einträgen gemeldet. Daher muss NtQueryDirectoryFile mindestens zweimal aufgerufen werden, außer in den oben aufgeführten Fällen, in denen nur ein Eintrag zurückgegeben wird, um den Inhalt eines gesamten Verzeichnisses aufzulisten.

Beim Aufrufen von NtQueryDirectoryFile werden möglicherweise Änderungen am Verzeichnis angezeigt, die parallel zu NtQueryDirectoryFile-Aufrufen vorgenommen werden. Dieses Verhalten hängt von der Implementierung des zugrunde liegenden Dateisystems ab.

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

Wenn NtQueryDirectoryFile mehrmals im selben Verzeichnis aufgerufen wird und ein anderer Vorgang den Inhalt dieses Verzeichnisses ändert, können änderungen je nach Zeitpunkt der Vorgänge angezeigt werden.

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

Aufrufer von NtQueryDirectoryFile 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 NtQueryDirectoryFile-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtQueryDirectoryFile" anstelle von "ZwQueryDirectoryFile" verwenden.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis