NtSetInformationFile-Funktion (ntifs.h)

Artikel
02/07/2025

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

Behandeln des Dateiobjekts. Dieses Handle wird durch einen erfolgreichen Aufruf von NtCreateFile- oder NtOpenFile-erstellt.

[out] IoStatusBlock

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Der Information Member erhält die Anzahl der in der Datei festgelegten Bytes.

[in] FileInformation

Zeigen Sie auf einen Puffer, der die für die Datei festzulegenden Informationen enthält. Die spezielle Struktur in diesem Puffer wird durch den parameter FileInformationClass bestimmt. Wenn der parameter FileInformationClass 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 Byte.

[in] FileInformationClass

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

wert FILE_INFORMATION_CLASS	Zurückgegebener Informationstyp
FileBasicInformation (4)	Ändern Sie die Informationen, die in einer FILE_BASIC_INFORMATION Struktur bereitgestellt werden. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess 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, die Datei zu löschen, wenn sie geschlossen oder abgebrochen wurde, eine zuvor angeforderte Löschung. Die Auswahl, ob gelöscht oder abgebrochen werden soll, wird in einer FILE_DISPOSITION_INFORMATION Struktur angegeben. Der Aufrufer muss die Datei mit dem DELETE-Flag geöffnet haben, das im parameter DesiredAccess festgelegt ist.
FilePositionInformation- (14)	Ändern Sie die aktuellen Dateiinformationen, die in einer FILE_POSITION_INFORMATION Struktur gespeichert sind.
FileEndOfFileInformation- (20)	Ändern Sie die aktuellen End-of-File-Informationen, 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 parameter DesiredAccess festgelegten FILE_WRITE_DATA Flag geöffnet haben.
FileValidDataLengthInformation (39)	Ändern Sie die aktuelle 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 Parameter DesiredAccess festgelegten FILE_WRITE_DATA Flag geöffnet haben. Nicht-Administratoren und Remotebenutzer müssen über das SeManageVolumePrivilege Berechtigung verfügen.
FileShortNameInformation- (40)	Ändern Sie den aktuellen Kurzdateinamen, 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 DesiredAccess DELETE-Flag im parameter DesiredAccess geöffnet haben.
FileIoPriorityHintInformation (43)	Ändern Sie den aktuellen IRP-Prioritätshinweis für das Dateihandle. Der neue Wert wird in einer FILE_IO_PRIORITY_HINT_INFORMATION Struktur angegeben. 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 einen Porthandle und einen Abschlussschlüssel angibt. Wenn der Porthandle nicht NULL ist, gibt dieses Handle einen neuen E/A-Vervollständigungsport an, der dem Dateihandle zugeordnet werden soll. Um den dem Dateihandle zugeordneten E/A-Vervollständigungsport zu entfernen, legen Sie das Porthandle in der Struktur auf NULL fest. Um ein Porthandle abzurufen, kann ein Benutzermodusaufrufer die CreateIoCompletionPort--Funktion aufrufen.
FileDispositionInformationEx- (64)	Anforderung, die Datei zu löschen oder einen zuvor angeforderten Löschvorgang abzubrechen. Die Auswahl, ob gelöscht oder abgebrochen werden soll, sowie Einstellungen für wann und wie der Löschvorgang ausgeführt werden soll, werden in einer FILE_DISPOSITION_INFORMATION_EX Struktur bereitgestellt. Der Aufrufer muss die Datei mit dem DELETE-Flag geöffnet haben, das im parameter DesiredAccess 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 parameter DesiredAccess 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 zu einer vorhandenen Datei, die in einer FILE_LINK_INFORMATION Struktur angegeben ist. Nicht alle Dateisysteme unterstützen feste Links; z. B. NTFS bewirkt, dass FAT nicht.
FileCaseSensitiveInformationForceAccessCheck (75)	Ändern Sie die Informationen, die in einer FILE_CASE_SENSITIVE_INFORMATION Struktur bereitgestellt werden. Der Aufrufer muss die Datei mit dem im parameter DesiredAccess festgelegten FILE_WRITE_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

NtSetInformationFile- gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück.

Bemerkungen

NtSetInformationFile ändert Informationen zu einer Datei. Es ignoriert jedes Element einer FILE_XXX-_INFORMATION-Struktur, die von einem bestimmten Gerät oder Dateisystem nicht unterstützt wird.

Wenn Sie FileInformationClass auf FileDispositionInformationfestlegen, können Sie anschließend FileHandle- an NtClose- übergeben, aber nicht an andere ZwXxxFile Routine. Da FileDispositionInformation bewirkt, dass die Datei zum Löschen markiert wird, handelt es sich um einen Programmierfehler, um alle nachfolgenden Vorgänge für das Handle zu versuchen, die nicht geschlossen werden.

Wenn Sie FileInformationClass- auf FilePositionInformationfestlegen und der vorherige Aufruf von NtCreateFile das FILE_NO_INTERMEDIATE_BUFFERING Flag im parameter CreateOptions enthalten, werden bestimmte Einschränkungen für das CurrentByteOffset Member der FILE_POSITION_INFORMATION-Struktur erzwungen. Weitere Informationen finden Sie unter NtCreateFile.

Wenn Sie FileInformationClass- auf FileEndOfFileInformation-festlegen und das EndOfFile-Element von FILE_END_OF_FILE_INFORMATION einen Offset über das aktuelle Ende der Dateimarke angibt, erweitert NtSetInformationFile die Datei und pads 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 speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.

Anmerkung

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 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