FILE_RENAME_INFORMATION-Struktur (ntifs.h)

Artikel
08/07/2023

Die FILE_RENAME_INFORMATION-Struktur wird verwendet, um eine Datei umzubenennen.

Syntax

typedef struct _FILE_RENAME_INFORMATION {
#if (_WIN32_WINNT >= _WIN32_WINNT_WIN10_RS1)
    union {
        BOOLEAN ReplaceIfExists;  // FileRenameInformation
        ULONG Flags;              // FileRenameInformationEx
    } DUMMYUNIONNAME;
#else
    BOOLEAN ReplaceIfExists;
#endif
    HANDLE RootDirectory;
    ULONG FileNameLength;
    WCHAR FileName[1];
} FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION;

Member

DUMMYUNIONNAME

DUMMYUNIONNAME.ReplaceIfExists

Legen Sie diesen Wert auf TRUE fest, um anzugeben, dass eine Datei mit dem angegebenen Namen bereits vorhanden ist, sie durch die angegebene Datei ersetzt werden soll. Legen Sie diesen Wert auf FALSE fest, wenn der Umbenennungsvorgang fehlschlagen soll, wenn bereits eine Datei mit dem angegebenen Namen vorhanden ist.

DUMMYUNIONNAME.Flags

Flags für den Umbenennungsvorgang. Dieses Feld gilt nur, wenn es mit der FileRenameInformationEx-Informationsklasse verwendet wird.

Die folgenden Werte sind möglich:

Wert	Bedeutung
FILE_RENAME_REPLACE_IF_EXISTS (0x00000001)	Wenn eine Datei mit dem angegebenen Namen bereits vorhanden ist, sollte sie durch die angegebene Datei ersetzt werden. Entspricht dem Feld ReplaceIfExists, das mit der FileRenameInformation-Informationsklasse verwendet wird.
FILE_RENAME_POSIX_SEMANTICS (0x00000002)	Wenn auch FILE_RENAME_REPLACE_IF_EXISTS angegeben ist, lassen Sie das Ersetzen einer Datei zu, auch wenn bereits Handles dafür vorhanden sind. Vorhandene Handles für die ersetzte Datei sind weiterhin für Vorgänge wie Lese- und Schreibvorgänge gültig. Jedes nachfolgende Öffnen des Zielnamens öffnet die umbenannte Datei, nicht die ersetzte Datei.
FILE_RENAME_SUPPRESS_PIN_STATE_INHERITANCE (0x00000004)	Wenn Sie eine Datei in ein neues Verzeichnis umbenennen, unterdrücken Sie alle Vererbungsregeln im Zusammenhang mit den attributen FILE_ATTRIBUTE_PINNED und FILE_ATTRIBUTE_UNPINNED der Datei.
FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE (0x00000008)	Wenn Sie eine Datei in ein neues Verzeichnis umbenennen, unterdrücken Sie alle Vererbungsregeln im Zusammenhang mit der Speicherreserve-ID-Eigenschaft der Datei.
FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE (0x00000010)	Wenn nicht auch FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE angegeben ist, ändern Sie beim Umbenennen einer Datei in ein neues Verzeichnis die Größe der betroffenen Speicherreservebereiche nach Bedarf automatisch, um zu verhindern, dass der sichtbare freie Speicherplatz auf dem Volume für den Benutzer zunimmt. Erfordert den Zugriff auf das Verwalten von Volumes.
FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE (0x00000020)	Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht ebenfalls angegeben ist, ändern Sie beim Umbenennen einer Datei in ein neues Verzeichnis die Größe der betroffenen Speicherreservebereiche nach Bedarf automatisch, um zu verhindern, dass der sichtbare freie Speicherplatz auf dem Volume verringert wird. Erfordert den Zugriff auf das Verwalten von Volumes.
FILE_RENAME_PRESERVE_AVAILABLE_SPACE (0x00000030)	Entspricht der Angabe von FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE und FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE.
FILE_RENAME_IGNORE_READONLY_ATTRIBUTE (0x00000040)	Wenn auch FILE_RENAME_REPLACE_IF_EXISTS angegeben ist, lassen Sie das Ersetzen einer Datei zu, auch wenn sie schreibgeschützt ist. Erfordert WRITE_ATTRIBUTES Zugriff auf die ersetzte Datei.
FILE_RENAME_FORCE_RESIZE_TARGET_SR (0x00000080)	Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht ebenfalls angegeben ist, vergrößern Sie beim Umbenennen einer Datei in ein neues Verzeichnis, das Teil eines anderen Speicherreservebereichs ist, immer den Speicherreservebereich des Zielverzeichnisses um die vollständige Größe der umbenannten Datei. Erfordert den Zugriff auf das Verwalten von Volumes.
FILE_RENAME_FORCE_RESIZE_SOURCE_SR (0x00000100)	Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht ebenfalls angegeben ist, verkleinern Sie beim Umbenennen einer Datei in ein neues Verzeichnis, das Teil eines anderen Speicherreservebereichs ist, immer den Speicherreservebereich des Quellverzeichnisses um die vollständige Größe der umbenannten Datei. Erfordert den Zugriff auf das Verwalten von Volumes.
FILE_RENAME_FORCE_RESIZE_SR (0x00000180)	Entspricht der Angabe von FILE_RENAME_FORCE_RESIZE_TARGET_SR und FILE_RENAME_FORCE_RESIZE_SOURCE_SR.

ReplaceIfExists

RootDirectory

Ein Handle, das IopOpenLinkOrRenameTarget verwendet, um das Zielverzeichnis zu öffnen.

Wenn die Datei nicht in ein anderes Verzeichnis verschoben wird oder das FileName-Element den vollständigen Pfadnamen enthält, ist dieser Member NULL. Andernfalls handelt es sich um ein Handle für das Stammverzeichnis, in dem sich die Datei befindet, nachdem sie umbenannt wurde.

Um zwei Geöffnete Vorgänge auszuführen, die keinen Freigabekonflikt verursachen, können Sie RootDirectory öffnen, indem Sie traverse | read-attribut. IopOpenLinkOrRenameTarget kann dann ein relatives Öffnen durchführen, indem FILE_WRITE_DATA | SYNCHRONISIEREN. Diese beiden Öffnen würden keinen Freigabekonflikt verursachen.

FileNameLength

Länge des neuen Namens für die Datei in Byte.

FileName[1]

Das erste Zeichen einer Breitzeichenzeichenfolge, die den neuen Namen für die Datei enthält. Darauf folgt im Arbeitsspeicher der rest der Zeichenfolge. Wenn das RootDirectory-Element NULL ist und die Datei in ein anderes Verzeichnis verschoben wird, gibt dieses Element den vollständigen Pfadnamen an, der der Datei zugewiesen werden soll. Andernfalls wird nur der Dateiname oder ein relativer Pfadname angegeben.

Hinweise

Die FILE_RENAME_INFORMATION-Struktur wird verwendet, um eine Datei umzubenennen. Dieser Vorgang kann auf eine der folgenden Arten ausgeführt werden:

Rufen Sie FltSetInformationFile oder ZwSetInformationFile auf, und übergeben Sie FileRenameInformation als Wert von FileInformationClass , und übergeben Sie einen vom Aufrufer zugeordneten Puffer, der als FILE_RENAME_INFORMATION-Struktur für den Wert von FileInformation formatiert ist. Der Parameter FileHandle gibt die datei an, die umbenannt werden soll.
Erstellen Sie ein IRP mit hauptfunktionscode IRP_MJ_SET_INFORMATION.

Dateisystem-Minifilter müssen FltSetInformationFile und nicht ZwSetInformationFile verwenden, um eine Datei umzubenennen.

Das Umbenennen einer Datei erfordert DELETE-Zugriff auf die Datei, damit der Verzeichniseintrag aus dem aktuellen übergeordneten Verzeichnis entfernt werden kann, sowie den entsprechenden Zugriff zum Erstellen des neuen Eintrags in der neuen übergeordneten Verzeichnisdatei.

Die Dateinamenzeichenfolge im FileName-Element muss in einem der folgenden Formulare angegeben werden.

Ein einfacher Dateiname. (Das RootDirectory-Element ist NULL.) In diesem Fall wird die Datei einfach innerhalb desselben Verzeichnisses umbenannt. Das heißt, der Umbenennungsvorgang ändert den Namen der Datei, aber nicht ihren Speicherort.
Ein vollqualifizierter Dateiname. (Das RootDirectory-Element ist NULL.) In diesem Fall ändern der Umbenennungsvorgang den Namen und den Speicherort der Datei.
Ein relativer Dateiname. In diesem Fall enthält das RootDirectory-Element ein Handle für das Zielverzeichnis für den Umbenennungsvorgang. Der Dateiname selbst muss ein einfacher Dateiname sein.

Allgemeine Regeln für Umbenennungsvorgänge:

Eine Datei oder ein Verzeichnis kann nur innerhalb eines Volumes umbenannt werden. Anders ausgedrückt: Ein Umbenennungsvorgang kann nicht dazu führen, dass eine Datei oder ein Verzeichnis auf ein anderes Volume verschoben wird.
Das Stammverzeichnis eines Volumes kann nicht umbenannt werden.
Wenn ReplaceIfExists auf FALSE festgelegt ist und das Ziel vorhanden ist, schlägt der Umbenennungsvorgang fehl.
Selbst wenn ReplaceIfExists auf TRUE festgelegt ist, schlägt der Umbenennungsvorgang weiterhin fehl, wenn bereits eine Datei mit demselben Namen vorhanden ist und ein Verzeichnis, eine schreibgeschützte Datei oder eine aktuell ausgeführte Datei ist.
Die Dateien und Verzeichnisse eines Volumes können nicht umbenannt werden, wenn es sich um ein schreibgeschütztes Volume handelt, z. B. ein CDFS-Volume oder ein schreibgeschütztes NTFS-Volume.

Besondere Regeln für das Umbenennen geöffneter Dateien:

Eine Datei kann nicht umbenannt werden, wenn sie über geöffnete Handles verfügt, es sei denn, sie ist nur aufgrund einer batchoprtunistischen Sperre (Oplock) geöffnet und der Batch-Oplock kann sofort unterbrochen werden.
Eine Datei kann nicht umbenannt werden, wenn eine Datei mit demselben Namen vorhanden ist und über geöffnete Handles verfügt (außer im zuvor beschriebenen Batch-Oplock-Fall).
Ein Verzeichnis kann nicht umbenannt werden, wenn es oder eines seiner Unterverzeichnisse eine Datei mit geöffneten Handles enthält (außer im zuvor beschriebenen Batch-Oplock-Fall).

Besondere Regeln für das Umbenennen von NTFS-Datenströmen:

Der Standardverzeichnisstream kann nicht umbenannt werden.
Der neue Name für den Stream muss mit einem Doppelpunkt (:) beginnen.
Ein Datenstrom kann nur innerhalb derselben Datei umbenannt werden. Anders ausgedrückt: Ein Umbenennungsvorgang kann nicht dazu führen, dass ein Datenstrom in eine andere Datei verschoben wird.
Ein Datenstrom in einem Verzeichnis kann nicht in den Standarddatenstrom umbenannt werden.
Wenn ReplaceIfExists auf TRUE festgelegt ist, ist der Umbenennungsvorgang nur erfolgreich, wenn ein Datenstrom mit demselben Namen nicht vorhanden ist oder ein Datenstrom der Länge null ist.
Das Umbenennen des Standarddatenstroms ist zulässig, aber dies ist keine echte Umbenennung, da ein Standarddatenstrom der Länge null zurückbleibt.

Die Größe des an ZwSetInformationFile oder FltSetInformationFile übergebenen FileInformationFile-Puffers muss = sizeof(FILE_RENAME_INFORMATION) plus die Größe der FileName-Zeichenfolge in Bytes sein>.

Anforderungen

Anforderung	Wert
Header	ntifs.h (include Ntifs.h, Fltkernel.h)

Weitere Informationen

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile

Freigeben über