NtQueryInformationFile-Funktion (ntifs.h)

Artikel
02/07/2025

Die NtQueryInformationFile Routine gibt verschiedene Arten von Informationen zu einem Dateiobjekt zurück. Siehe auch NtQueryInformationByName, die für einige Dateiinformationsklassen effizienter verwendet werden können.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parameter

[in] FileHandle

Behandeln eines Dateiobjekts. Das Handle wird durch einen erfolgreichen Aufruf von NtCreateFile oder NtOpenFile-oder einer entsprechenden Datei erstellt oder geöffnet.

[out] IoStatusBlock

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum Vorgang empfängt. Das Information Member empfängt die Anzahl der Bytes, die diese Routine tatsächlich in den FileInformation- Puffer schreibt.

[out] FileInformation

Zeigen Sie auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine die angeforderten Informationen zum Dateiobjekt schreibt. Der parameter FileInformationClass gibt den Typ der Informationen an, die der Aufrufer anfordert.

[in] Length

Die Größe des Puffers in Byte, auf den FileInformationverweist.

[in] FileInformationClass

Gibt den Typ der Informationen an, die über die Datei zurückgegeben werden sollen, im Puffer, auf den FileInformation verweist. Geräte- und Zwischentreiber können eine der folgenden FILE_INFORMATION_CLASS Werte angeben (von niedrigstem bis höchsten Enumerationswert):

wert FILE_INFORMATION_CLASS	Zurückgegebener Informationstyp
FileBasicInformation (4)	Eine FILE_BASIC_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben.
FileStandardInformation- (5)	Eine FILE_STANDARD_INFORMATION Struktur. Der Aufrufer kann diese Informationen abfragen, solange die Datei geöffnet ist, ohne bestimmte Anforderungen für DesiredAccess-.
FileInternalInformation- (6)	Eine FILE_INTERNAL_INFORMATION Struktur. Diese Struktur gibt eine 64-Bit-Datei-ID an, die eine Datei in NTFS eindeutig identifiziert. Auf anderen Dateisystemen ist diese Datei-ID nicht garantiert eindeutig.
FileEaInformation (7)	Eine FILE_EA_INFORMATION Struktur. Diese Struktur gibt die Größe des erweiterten Attributblocks an, der der Datei zugeordnet ist.
FileAccessInformation- (8)	Eine FILE_ACCESS_INFORMATION Struktur. Diese Struktur enthält eine Zugriffsmaske. Weitere Informationen zu Zugriffsmasken finden Sie unter ACCESS_MASK.
FileNameInformation- (9)	Eine FILE_NAME_INFORMATION Struktur. Die Struktur kann den vollständigen Pfad der Datei oder nur einen Teil davon enthalten. Der Aufrufer kann diese Informationen abfragen, solange die Datei geöffnet ist, ohne bestimmte Anforderungen für DesiredAccess-. Weitere Informationen zur Syntax des Dateinamens finden Sie weiter unten in diesem Thema im Abschnitt "Hinweise".
FilePositionInformation- (14)	Eine FILE_POSITION_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem DesiredAccess- FILE_READ_DATA- oder FILE_WRITE_DATA Flag geöffnet haben, das im Parameter DesiredAccess angegeben ist, und mit dem im parameter CreateOptions angegebenen FILE_SYNCHRONOUS_IO_ALERT- oder FILE_SYNCHRONOUS_IO_NONALERT Flag.
FileModeInformation- (16)	Eine FILE_MODE_INFORMATION Struktur. Diese Struktur enthält eine Reihe von Flags, die den Modus angeben, in dem auf die Datei zugegriffen werden kann. Diese Flags sind eine Teilmenge der Optionen, die im CreateOptions Parameter der IoCreateFile Routine angegeben werden können.
FileAlignmentInformation (17)	Eine FILE_ALIGNMENT_INFORMATION Struktur. Der Aufrufer kann diese Informationen abfragen, solange die Datei geöffnet ist, ohne bestimmte Anforderungen für DesiredAccess-. Diese Informationen sind nützlich, wenn die Datei mit dem im CreateOptions Parameter angegebenen FILE_NO_INTERMEDIATE_BUFFERING Flag geöffnet wurde.
FileAllInformation- (18)	Eine FILE_ALL_INFORMATION Struktur. Durch die Kombination mehrerer Dateiinformationsstrukturen in einer einzigen Struktur reduziert FILE_ALL_INFORMATION die Anzahl der Abfragen, die zum Abrufen von Informationen zu einer Datei erforderlich sind.
FileAlternateNameInformation (21)	Eine FILE_ALL_INFORMATION Struktur, in der die alternativen Namensinformationen für eine Datei (8.3-Formatname) zurückgegeben werden sollen.
FileStreamInformation- (22)	Ein Puffer von FILE_STREAM_INFORMATION Strukturen, in denen die Datenströme einer Datei oder eines Verzeichnisses aufgelistet werden sollen.
FileCompressionInformation (28)	Eine FILE_COMPRESSION_INFORMATION Struktur, in der Komprimierungsinformationen für eine Datei zurückgegeben werden sollen.
FileNetworkOpenInformation (34)	Eine FILE_NETWORK_OPEN_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben.
FileAttributeTagInformation- (35)	Eine FILE_ATTRIBUTE_TAG_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben.
FileIoPriorityHintInformation (43)	Eine FILE_IO_PRIORITY_HINT_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_DATA Flag geöffnet haben.
FileSfioReserveInformation (44)	Eine FILE_SFIO_RESERVE_INFORMATION Struktur.
FileHardLinkInformation- (46)	Eine FILE_LINKS_INFORMATION Struktur.
FileNormalizedNameInformation (48)	Eine FILE_NAME_INFORMATION Struktur, in der der normalisierte Name einer Datei zurückgegeben werden soll.
FileIsRemoteDeviceInformation (51)	Eine FILE_IS_REMOTE_DEVICE_INFORMATION Struktur. Der Aufrufer kann diese Informationen abfragen, solange die Datei geöffnet ist, ohne bestimmte Anforderungen für DesiredAccess-.
FileStandardLinkInformation- (54)	Eine FILE_STANDARD_LINK_INFORMATION Struktur.
FileIdInformation- (59)	Eine FILE_ID_INFORMATION Struktur.
FileDesiredStorageClassInformation (67)	Eine FILE_DESIRED_STORAGE_CLASS_INFORMATION Struktur.
FileStatInformation- (68)	FILE_STAT_INFORMATION
FileStatLxInformation- (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Eine FILE_CASE_SENSITIVE_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben. Dieser Wert ist ab Windows 10, Version 1803, verfügbar.
FileStorageReserveIdInformation (74)	Eine FILE_STORAGE_RESERVE_ID_INFORMATION Struktur.
FileCaseSensitiveInformationForceAccessCheck (75)	Eine FILE_CASE_SENSITIVE_INFORMATION Struktur. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben. Dies ist eine spezielle Version des FileCaseSensitiveInformation-Vorgangs, der verwendet wird, um zu erzwingen, dass der IOManager Zugriffsprüfungen für den Kernelmodustreiber durchführt, ähnlich wie die Prüfungen, die für einen Benutzermodus-Aufrufer gelten. Dieser Vorgang wird nur vom IOManager erkannt, und ein Dateisystem sollte ihn nie empfangen. Dieser Wert ist ab Windows 10, Version 1803, verfügbar.
FileKnownFolderInformation (76)	Eine FILE_KNOWN_FOLDER_INFORMATION Struktur. Ab Windows Server 2022 verfügbar.

Rückgabewert

NtQueryInformationFile- gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Fehlercode zurück.

Bemerkungen

NtQueryInformationFile Informationen zum angegebenen Dateiobjekt zurück. Beachten Sie, dass es in einem Element einer FILE_XXX-_INFORMATION Struktur null zurückgibt, die von einem bestimmten Gerät oder Dateisystem nicht unterstützt wird.

Wenn FileInformationClass = FileNameInformation, wird der Dateiname in der FILE_NAME_INFORMATION Struktur zurückgegeben. Die genaue Syntax des Dateinamens hängt von einer Reihe von Faktoren ab:

Wenn Sie die Datei geöffnet haben, indem Sie einen vollständigen Pfad zu NtCreateFileübermitteln, gibt NtQueryInformationFile diesen vollständigen Pfad zurück.
Wenn das ObjectAttributes->RootDirectory- Handle mit dem Namen in einem Aufruf von NtCreateFilegeöffnet wurde und anschließend die Datei von NtCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt NtQueryInformationFile den vollständigen Pfad zurück.
Wenn das ObjectAttributes->RootDirectory Handle durch Datei-ID (mithilfe des FILE_OPEN_BY_FILE_ID-Flags) in einem Aufruf von NtCreateFilegeöffnet wurde und anschließend die Datei von NtCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt NtQueryInformationFile den relativen Pfad zurück.
Wenn der Benutzer jedoch SeChangeNotifyPrivilege hat (in der Microsoft Windows SDK-Dokumentation beschrieben), gibt NtQueryInformationFile den vollständigen Pfad in allen Fällen zurück.
Wenn nur der relative Pfad zurückgegeben wird, beginnt die Dateinamenzeichenfolge nicht mit einem umgekehrten Schrägstrich.
Wenn der vollständige Pfad und der Dateiname zurückgegeben werden, beginnt die Zeichenfolge unabhängig vom Speicherort mit einem einzelnen umgekehrten Schrägstrich. Daher wird die Datei C:\dir1\dir2\filename.ext als \dir1\dir2\filename.ext angezeigt, während die Datei \server\share\dir1\dir2\filename.ext als \server\share\dir1\dir2\filename.ext angezeigt wird.

Wenn NtQueryInformationFile- aufgrund eines Pufferüberlaufs fehlschlägt, sollten Treiber, die FileNameInformation- implementieren, so viele WCHAR-Zeichen des Dateinamens zurückgeben, wie in den Puffer passen und die vollständige Länge angeben, die im FileNameLength Parameter der FILE_NAME_INFORMATION Struktur erforderlich ist. Sie sollten die Abfrage erneut mit der Dateinamenlänge wiederherstellen, damit Sie den vollständigen Dateinamen abrufen können. Treiber, die diesem Muster nicht folgen, erfordern möglicherweise eine graduelle Erhöhung der Länge, bis sie den vollständigen Dateinamen abrufen. Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber-.

Aufrufer von NtQueryInformationFile- müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.

Anmerkung

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtQueryInformationFile" anstelle von "ZwQueryInformationFile" 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 2000.
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis