NtQueryDirectoryFile-Funktion (ntifs.h)
Die NtQueryDirectoryFile Routine gibt verschiedene Arten von Informationen zu Dateien im durch ein bestimmtes Dateihandle angegebenen Verzeichnis zurück.
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 Status "Signaled" festgelegt ist. Dieser Parameter ist optional und kann NULL sein. Er muss NULL sein, wenn der Aufrufer auf die FileHandle- auf den Signalstatus 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 ein APC bereitstellt oder ein E/A-Vervollständigungsobjekt dem Dateiobjekt zugeordnet ist. Wenn der Vorgang abgeschlossen ist, wird dieser Kontext an das APC übergeben, wenn eins angegeben wurde, oder als Teil der Abschlussmeldung enthalten ist, die der E/A-Manager an das zugeordnete E/A-Abschlussobjekt 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 den endgültigen Abschlussstatus und Informationen zum Vorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der In den FileInformation Puffer geschriebenen Bytes im Information Member 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 Byte, auf den FileInformationverweist. Der Aufrufer sollte diesen Parameter gemäß der angegebenen FileInformationClassfestlegen.
[in] FileInformationClass
Der Informationstyp, der über Dateien im Verzeichnis zurückgegeben werden soll. 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 NtQueryDirectoryFile nur den ersten gefundenen Eintrag zurück.
[in, optional] FileName
Ein optionaler Zeiger auf eine vom Aufrufer zugewiesene Unicode-Zeichenfolge mit dem Namen einer Datei (oder mehrerer Dateien, wenn Wildcards verwendet werden) innerhalb des durch FileHandleangegebenen Verzeichnis. Dieser Parameter ist optional und kann NULL sein.
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.
Die FileName- wird als Suchausdruck verwendet und wird beim ersten Aufruf von NtQueryDirectoryFile für ein bestimmtes Handle erfasst. Nachfolgende Aufrufe von NtQueryDirectoryFile verwenden den Suchausdruckssatz im ersten Aufruf. Der FileName Parameter, der an nachfolgende Aufrufe übergeben wird, wird 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.
Wenn die NtQueryDirectoryFile- Routine für ein bestimmtes Handle aufgerufen wird, wird der RestartScan Parameter behandelt, als ob er auf TRUE-festgelegt wurde, unabhängig vom Wert. Bei nachfolgenden NtQueryDirectoryFile- wird der Wert des parameters RestartScan berücksichtigt.
Rückgabewert
Die NtQueryDirectoryFileRoutine gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Der Satz von Fehlerstatuswerten, 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 IoStatusblockgeschrieben wurden. Eine Liste der möglichen Fehlercodes finden Sie unter NtQueryDirectoryFileEx-.
Bemerkungen
Die NtQueryDirectoryFile Routine gibt Informationen zu Dateien zurück, die im Verzeichnis enthalten sind, das durch FileHandledargestellt wird.
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 einen bestimmten FileHandle-enthalten sind.
Wenn mindestens ein übereinstimmenden Eintrag vorhanden ist, erstellt NtQueryDirectoryFile für jeden Eintrag eine FILE_XXX-_INFORMATION-Struktur und speichert sie 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:
- Ein Eintrag, wenn ReturnSingleEntry-TRUE- 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 NtQueryDirectoryFiledie für den ersten gefundenen Eintrag erstellte Struktur zu groß ist, um in den Ausgabepuffer einzupassen, schreibt die Routine den festen Teil der Struktur in den Ausgabepuffer. Die Routine schreibt dann in den Ausgabepuffer so viele der FileName- Zeichenfolge, wie sie passen. (Der feste Teil der Struktur besteht aus allen Feldern mit Ausnahme der endgültigen FileName- Zeichenfolge. Im 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 zu halten.) In diesem Fall gibt NtQueryDirectoryFile einen geeigneten Statuswert wie STATUS_BUFFER_OVERFLOW zurück.
Bei jedem Aufruf gibt NtQueryDirectoryFile- so viele FILE_XXX-_INFORMATION Strukturen (einen pro Verzeichniseintrag) zurück, wie sie vollständig im Puffer enthalten sein können, auf den FileInformationverweist. 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 zurück, legt jedoch IoStatusblock-fest –>Information = 0, um den Aufrufer dieser Bedingung zu benachrichtigen. In diesem Fall sollte der Aufrufer einen größeren Puffer zuweisen und NtQueryDirectoryFile- erneut aufrufen. 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 NtQueryDirectoryFile- mindestens zweimal aufgerufen werden, um den Inhalt eines gesamten Verzeichnisses aufzählen zu können.
Beim Aufrufen 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 entsprechenden Statuswert wie STATUS_NO_MORE_FILES.
Wenn NtQueryDirectoryFile- mehrmals im selben Verzeichnis aufgerufen wird und ein anderer Vorgang den Inhalt dieses Verzeichnisses ändert, werden alle Änderungen je nach Zeitpunkt der Vorgänge möglicherweise oder nicht angezeigt.
NtQueryDirectoryFilegibt null in einem 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 speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.
Informationen zu anderen Dateiinformationsabfrageroutinen finden Sie unter File Objects.
Anmerkung
Wenn der Aufruf der NtQueryDirectoryFile--Funktion im Benutzermodus auftritt, 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 behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXXX und ZwXXX Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | HwStorPortProhibitedDIs, PowerIrpDDis |