NtSetInformationFile-Funktion (ntifs.h)

Artikel
07/11/2023

Die NtSetInformationFile-Routine ändert verschiedene Arten von Informationen zu einem Dateiobjekt.

Syntax

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

Parameter

[in] FileHandle

Handle für das Dateiobjekt. Dieses Handle wird durch einen erfolgreichen Aufruf von NtCreateFile oder NtOpenFile erstellt.

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Vorgang empfängt. Das Information-Element empfängt die Anzahl von Bytes, die für die Datei festgelegt sind.

[in] FileInformation

Zeiger auf einen Puffer, der die für die Datei festzulegenden Informationen enthält. Die spezifische Struktur in diesem Puffer wird durch den FileInformationClass-Parameter bestimmt. Wenn der FileInformationClass-Parameter beispielsweise auf die FileDispositionInformationEx-Konstante festgelegt ist, sollte dieser Parameter ein Zeiger auf eine FILE_DISPOSITION_INFORMATION_EX-Struktur sein.

[in] Length

Die Größe des FileInformation-Puffers in Bytes.

[in] FileInformationClass

Der Typ der Informationen, die im Puffer bereitgestellt werden, auf den von FileInformation verwiesen wird, der für die Datei festgelegt werden soll. Geräte- und Zwischentreiber können einen der folgenden FILE_INFORMATION_CLASS-Werte angeben.

FILE_INFORMATION_CLASS Wert	Typ der zurückgegebenen Informationen
FileBasicInformation (4)	Ändern Sie die Informationen, die in einer FILE_BASIC_INFORMATION-Struktur bereitgestellt werden. Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter festgelegten FILE_WRITE_ATTRIBUTES-Flag geöffnet haben.
FileRenameInformation (10)	Ändern Sie den aktuellen Dateinamen, der in einer FILE_RENAME_INFORMATION-Struktur angegeben wird. Der Aufrufer muss über DELETE-Zugriff auf die Datei verfügen.
FileDispositionInformation (13)	Anforderung zum Löschen der Datei, wenn sie geschlossen wird, oder Abbrechen eines zuvor angeforderten Löschvorgangs. Die Auswahl, ob gelöscht oder abgebrochen werden soll, wird in einer FILE_DISPOSITION_INFORMATION-Struktur angegeben. Der Aufrufer muss die Datei geöffnet haben, wobei das DELETE-Flag im DesiredAccess-Parameter festgelegt ist.
FilePositionInformation (14)	Ändern Sie die aktuellen Dateiinformationen, die in einer FILE_POSITION_INFORMATION-Struktur gespeichert sind.
FileEndOfFileInformation (20)	Ändern Sie die aktuellen Informationen zum Dateiende, die in einer FILE_END_OF_FILE_INFORMATION-Struktur bereitgestellt werden. Der Vorgang kann die Datei entweder abschneiden oder erweitern. Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter festgelegten FILE_WRITE_DATA-Flag geöffnet haben.
FileValidDataLengthInformation (39)	Ändern Sie die aktuell gültige Datenlänge für die Datei, die in einer FILE_VALID_DATA_LENGTH_INFORMATION-Struktur angegeben wird. Die Datei muss sich auf einem NTFS-Volume befinden, und der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter festgelegten FILE_WRITE_DATA-Flag geöffnet haben. Nicht-Administratoren und Remotebenutzer müssen über die SeManageVolumePrivilege-Berechtigung verfügen.
FileShortNameInformation (40)	Ändern Sie den aktuellen kurzen Dateinamen, der in einer FILE_NAME_INFORMATION-Struktur angegeben wird. Die Datei muss sich auf einem NTFS-Volume befinden, und der Aufrufer muss die Datei mit dem DELETE-Flag DesiredAccess geöffnet haben, das im DesiredAccess-Parameter festgelegt ist.
FileIoPriorityHintInformation (43)	Ändern Sie den aktuellen IRP-Standardprioritätshinweis für das Dateihandle. Der neue Wert wird in einer FILE_IO_PRIORITY_HINT_INFORMATION-Struktur bereitgestellt. Diese Struktur muss 8 Byte ausgerichtet sein.
FileReplaceCompletionInformation (61)	Ändern oder entfernen Sie den E/A-Vervollständigungsport für das angegebene Dateihandle. Der Aufrufer stellt einen Zeiger auf eine FILE_COMPLETION_INFORMATION-Struktur bereit, die ein Porthandle und einen Abschlussschlüssel angibt. Wenn das Porthandle ungleich NULL ist, gibt dieses Handle einen neuen E/A-Vervollständigungsport an, der dem Dateihandle zugeordnet werden soll. Um den E/A-Vervollständigungsport zu entfernen, der dem Dateihandle zugeordnet ist, legen Sie das Porthandle in der Struktur auf NULL fest. Um ein Porthandle zu erhalten, kann ein Benutzermodusaufrufer die CreateIoCompletionPort-Funktion aufrufen.
FileDispositionInformationEx (64)	Anforderung zum Löschen der Datei oder Abbrechen eines zuvor angeforderten Löschvorgangs. Die Auswahl, ob gelöscht oder abgebrochen werden soll, sowie Die Einstellungen, wann und wie der Löschvorgang ausgeführt werden soll, werden in einer FILE_DISPOSITION_INFORMATION_EX-Struktur bereitgestellt. Der Aufrufer muss die Datei geöffnet haben, wobei das DELETE-Flag im DesiredAccess-Parameter festgelegt ist.
FileCaseSensitiveInformation (71)	Ändern Sie die Informationen, die in einer FILE_CASE_SENSITIVE_INFORMATION-Struktur bereitgestellt werden. Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter festgelegten FILE_WRITE_ATTRIBUTES-Flag geöffnet haben. Dieser Wert ist ab Windows 10 Version 1803 verfügbar.
FileLinkInformation (72)	Erstellen Sie eine feste Verknüpfung mit einer vorhandenen Datei, die in einer FILE_LINK_INFORMATION-Struktur angegeben ist. Nicht alle Dateisysteme unterstützen feste Links. Beispielsweise funktioniert NTFS, während FAT dies nicht tut.
FileCaseSensitiveInformationForceAccessCheck (75)	Ändern Sie die Informationen, die in einer FILE_CASE_SENSITIVE_INFORMATION-Struktur bereitgestellt werden. Der Aufrufer muss die Datei mit dem im DesiredAccess-Parameter festgelegten FILE_WRITE_ATTRIBUTES-Flag geöffnet haben. Dies ist eine spezielle Version des FileCaseSensitiveInformation-Vorgangs, der verwendet wird, um den IOManager zu erzwingen, Zugriffsprüfungen für den Kernelmodustreiber durchzuführen, ähnlich den Ü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

NtSetInformationFile gibt STATUS_SUCCESS oder einen geeigneten Fehler status zurück.

Hinweise

NtSetInformationFile ändert Informationen zu einer Datei. Es ignoriert alle Member einer FILE_XXX_INFORMATION-Struktur , die von einem bestimmten Gerät oder Dateisystem nicht unterstützt wird.

Wenn Sie FileInformationClass auf FileDispositionInformation festlegen, können Sie FileHandle anschließend an NtClose, aber nicht an eine andere ZwXxx-Dateiroutine übergeben. Da FileDispositionInformation bewirkt, dass die Datei zum Löschen markiert wird, ist es ein Programmierfehler, jeden nachfolgenden Vorgang für das Handle außer dem Schließen zu versuchen.

Wenn Sie FileInformationClass auf FilePositionInformation festlegen und der vorangehende Aufruf von NtCreateFile das FILE_NO_INTERMEDIATE_BUFFERING-Flag im CreateOptions-Parameter enthält, werden bestimmte Einschränkungen für das CurrentByteOffset-Element der FILE_POSITION_INFORMATION-Struktur erzwungen. Weitere Informationen finden Sie unter NtCreateFile.

Wenn Sie FileInformationClass auf FileEndOfFileInformation festlegen und der EndOfFile-Member von FILE_END_OF_FILE_INFORMATION einen Offset über die aktuelle Dateiendemarkierung hinaus angibt, erweitert NtSetInformationFile die Datei und füllt die Erweiterung mit Nullen.

Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber.

Aufrufer von NtSetInformationFile müssen unter IRQL = PASSIVE_LEVEL und mit aktivierten speziellen Kernel-APCs ausgeführt werden.

Hinweis

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, verwenden Sie den Namen "NtSetInformationFile" anstelle von "ZwSetInformationFile".

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 Versionen NtXxx**** und ZwXxx**** einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der 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