ZwQueryInformationFile-Funktion (wdm.h)

Artikel
02/27/2024

Die ZwQueryInformationFile-Routine gibt verschiedene Arten von Informationen zu einem Dateiobjekt zurück.

Syntax

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [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 ZwCreateFile oder ZwOpenFile 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.

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.
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.
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.
FileKnownFolderInformation (76)	Eine FILE_KNOWN_FOLDER_INFORMATION-Struktur . Verfügbar ab Windows Server 2022.

Rückgabewert

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

Hinweise

ZwQueryInformationFile 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 an ZwCreateFile übermitteln, gibt ZwQueryInformationFile diesen vollständigen Pfad zurück.
Wenn das ObjectAttributes-RootDirectory-Handle> in einem Aufruf von ZwCreateFile mit dem Namen geöffnet wurde und die Datei anschließend von ZwCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt ZwQueryInformationFile den vollständigen Pfad zurück.
Wenn das ObjectAttributes-RootDirectory-Handle> durch die Datei-ID (unter Verwendung des FILE_OPEN_BY_FILE_ID Flags) in einem Aufruf von ZwCreateFile geöffnet wurde und die Datei anschließend von ZwCreateFile relativ zu diesem Stammverzeichnishandle geöffnet wurde, gibt ZwQueryInformationFile den relativen Pfad zurück.
Wenn der Benutzer jedoch über SeChangeNotifyPrivilege verfügt, gibt ZwQueryInformationFile 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 der vollständige Dateiname zurückgegeben werden, beginnt die Zeichenfolge unabhängig von ihrem 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 ZwQueryInformationFile 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 mithilfe der Dateinamenlänge erneut ausführen, 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 ZwQueryInformationFile müssen unter IRQL = PASSIVE_LEVEL und mit aktivierten speziellen Kernel-APCs ausgeführt werden.

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, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Versionen NtXxx**** und ZwXxx**** einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Native System Services-Routinen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)