ZwSetInformationFile-Funktion (wdm.h)

Artikel
11/07/2024

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

Behandeln des Dateiobjekts. Dieses Handle wird durch einen erfolgreichen Aufruf von ZwCreateFile oder ZwOpenFileerstellt.

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

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 parameter DesiredAccess festgelegten FILE_WRITE_ATTRIBUTES Flag geöffnet haben.
FileDispositionInformation-	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.
FileDispositionInformationEx-	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.
FileEndOfFileInformation	Ä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.
FileIoPriorityHintInformation	Ä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.
FileLinkInformation-	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.
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 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.
FileIoCompletionNotificationInformation-	Ändern Sie die E/A-Benachrichtigungskennzeichnungen der Datei. Unterstützt dieselben Flags wie SetFileCompletionNotificationModes.
FileValidDataLengthInformation	Ä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.
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 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.

Rückgabewert

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

Bemerkungen

ZwSetInformationFile ä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 ZwClose ü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 ZwCreateFile 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 ZwCreateFile.

Wenn Sie FileInformationClass auf FileEndOfFileInformationfestlegen und das EndOfFile-Element von FILE_END_OF_FILE_INFORMATION einen Offset über das aktuelle Ende der Dateimarke angibt, erweitert ZwSetInformationFile 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 ZwSetInformationFile- müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.

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 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
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)