FILE_RENAME_INFORMATION-Struktur (ntifs.h)

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:

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.

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

Weitere Informationen

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile