ZwSetInformationFile-Funktion (wdm.h)

Artikel
03/08/2023

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

Syntax

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

FileInformationClass Wert	Bedeutung
FileBasicInformation	Ä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.
FileDispositionInformation	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.
FileDispositionInformationEx	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 mit dem delete*-Flag geöffnet haben, das im DesiredAccess-Parameter* festgelegt ist.
FileEndOfFileInformation	Ä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.
FileIoPriorityHintInformation	Ä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.
FileLinkInformation	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.
FilePositionInformation	Ändern Sie die aktuellen Dateiinformationen, die in einer FILE_POSITION_INFORMATION-Struktur gespeichert sind.
FileRenameInformation	Ä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.
FileShortNameInformation	Ä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.
FileValidDataLengthInformation	Ä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.
FileReplaceCompletionInformation	Ä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.

Rückgabewert

ZwSetInformationFile gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück.

Hinweise

ZwSetInformationFile ä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 ZwClose, 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 vorherige Aufruf von ZwCreateFile das flag FILE_NO_INTERMEDIATE_BUFFERING 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 ZwCreateFile.

Wenn Sie FileInformationClass auf FileEndOfFileInformation festlegen und der EndOfFile-Member von FILE_END_OF_FILE_INFORMATION einen Offset angibt, der über die aktuelle Dateiendemarkierung hinausgeht, erweitert ZwSetInformationFile 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 ZwSetInformationFile 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 "NtSetInformationFile" anstelle von "ZwSetInformationFile" 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
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)