NtQueryInformationFile-Funktion (ntifs.h)

Artikel
02/27/2024

Die NtQueryInformationFile-Routine gibt verschiedene Arten von Informationen zu einem Dateiobjekt zurück. Siehe auch NtQueryInformationByName, das für einige Dateiinformationsklassen effizienter verwendet werden kann.

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 Dateierstellungs- oder Open-Routine erstellt.

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum Vorgang empfängt. Das Information-Element empfängt die Anzahl von Bytes, die diese Routine tatsächlich in den FileInformation-Puffer schreibt.

[out] FileInformation

Zeiger 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 Bytes, auf den fileInformation verweist.

[in] FileInformationClass

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

FILE_INFORMATION_CLASS Wert	Art der zurückgegebenen Informationen
FileBasicInformation (4)	Eine FILE_BASIC_INFORMATION-Struktur . Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter 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 besondere Anforderungen an 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 Blocks mit erweiterten Attributen 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 besondere Anforderungen an DesiredAccess. Weitere Informationen zur Dateinamensyntax 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 DesiredAccess-Parameter angegeben ist, und mit dem im CreateOptions-Parameter 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 besondere Anforderungen an 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 von 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 (name des Formats 8.3) zurückgegeben werden sollen.
FileStreamInformation (22)	Ein Puffer aus 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 DesiredAccess-Parameter angegebenen FILE_READ_ATTRIBUTES Flag geöffnet haben.
FileAttributeTagInformation (35)	Eine FILE_ATTRIBUTE_TAG_INFORMATION-Struktur . Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter 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 DesiredAccess-Parameter 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 besondere Anforderungen an 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 DesiredAccess-Parameter 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 DesiredAccess-Parameter 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 Überprüfungen, die für einen Benutzermodusaufrufer 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 . Verfügbar ab Windows Server 2022.

Rückgabewert

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

Hinweise

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

Bei 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> in einem Aufruf von NtCreateFile mit dem Namen geöffnet wurde und die Datei anschließend von NtCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt NtQueryInformationFile den vollständigen Pfad zurück.
Wenn das Handle ObjectAttributes-RootDirectory> bei einem Aufruf von NtCreateFile durch die Datei-ID (unter Verwendung des FILE_OPEN_BY_FILE_ID-Flags) geöffnet wurde und die Datei anschließend von NtCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt NtQueryInformationFile den relativen Pfad zurück.
Wenn der Benutzer jedoch über SeChangeNotifyPrivilege verfügt (in der Microsoft Windows SDK-Dokumentation beschrieben), gibt NtQueryInformationFile in allen Fällen den vollständigen Pfad 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 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\dateiname.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 ausführen, indem Sie die Länge des Dateinamens verwenden, damit Sie den vollständigen Dateinamen abrufen können. Treiber, die diesem Muster nicht folgen, erfordern möglicherweise eine allmähliche 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 aktivierten speziellen Kernel-APCs ausgeführt werden.

Hinweis

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 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 systemeigenen Systemdienstroutinen.

Anforderungen

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