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;
Angehörige
DUMMYUNIONNAME
DUMMYUNIONNAME.ReplaceIfExists
Legen Sie auf TRUE fest, um anzugeben, dass eine Datei mit dem angegebenen Namen bereits vorhanden ist, durch die angegebene Datei ersetzt werden soll. Wird auf FALSE festgelegt, wenn der Umbenennungsvorgang fehlschlägt, 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.
Hier sind die möglichen Werte:
| Wert | Bedeutung |
|---|---|
| FILE_RENAME_REPLACE_IF_EXISTS (0x00000001) | Wenn bereits eine Datei mit dem angegebenen Namen vorhanden ist, sollte sie durch die angegebene Datei ersetzt werden. Entspricht dem ReplaceIfExists-Feld, das mit der FileRenameInformation-Informationsklasse verwendet wird. |
| FILE_RENAME_POSIX_SEMANTICS (0x00000002) | Wenn FILE_RENAME_REPLACE_IF_EXISTS ebenfalls angegeben ist, lassen Sie das Ersetzen einer Datei auch dann zu, wenn es vorhandene Handles gibt. Vorhandene Handles für die ersetzte Datei sind weiterhin gültig für Vorgänge wie Lese- und Schreibzugriff. Alle nachfolgenden Öffnen des Zielnamens öffnen 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 dem FILE_ATTRIBUTE_PINNED und FILE_ATTRIBUTE_UNPINNED Attributen 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 Eigenschaft der Speicherreserve-ID der Datei. |
| FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE (0x00000010) | Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht auch angegeben ist, ändern Sie beim Umbenennen einer Datei in ein neues Verzeichnis die Größe der betroffenen Speicherreservebereiche bei Bedarf automatisch, um zu verhindern, dass der Benutzer sichtbaren freien Speicherplatz auf dem Volume erhöht. Erfordert die Verwaltung des Volumezugriffs. |
| FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE (0x00000020) | Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht auch angegeben ist, ändern Sie bei der Umbenennung einer Datei in ein neues Verzeichnis die Größe der betroffenen Speicherreservebereiche bei Bedarf automatisch, um zu verhindern, dass der Benutzer sichtbaren freien Speicherplatz auf dem Volume verringert. Erfordert die Verwaltung des Volumezugriffs. |
| 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 FILE_RENAME_REPLACE_IF_EXISTS auch angegeben ist, lassen Sie das Ersetzen einer Datei auch dann zu, 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 auch angegeben ist, wird beim Umbenennen einer Datei in ein neues Verzeichnis, das Teil eines anderen Speicherreservebereichs ist, immer der Speicherreservebereich des Zielverzeichnisses um die vollständige Größe der umbenannten Datei vergrößert. Erfordert die Verwaltung des Volumezugriffs. |
| FILE_RENAME_FORCE_RESIZE_SOURCE_SR (0x00000100) | Wenn FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE nicht auch 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 die Verwaltung des Volumezugriffs. |
| FILE_RENAME_FORCE_RESIZE_SR (0x00000180) | Entspricht der Angabe von FILE_RENAME_FORCE_RESIZE_TARGET_SR und FILE_RENAME_FORCE_RESIZE_SOURCE_SR. |
ReplaceIfExists
Legen Sie auf TRUE fest, um anzugeben, dass eine Datei mit dem angegebenen Namen bereits vorhanden ist, durch die angegebene Datei ersetzt werden soll. Wird auf FALSE festgelegt, wenn der Umbenennungsvorgang fehlschlägt, wenn bereits eine Datei mit dem angegebenen Namen vorhanden ist.
RootDirectory
Ein Handle, das IopOpenLinkOrRenameTarget zum Öffnen des Zielverzeichnisses verwendet.
Wenn die Datei nicht in ein anderes Verzeichnis verschoben wird oder das FileName Member den vollständigen Pfadnamen enthält, ist dieses Element NULL. Andernfalls handelt es sich um ein Handle für das Stammverzeichnis, unter 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 anfordern | read-attribute. IopOpenLinkOrRenameTarget kann dann ein relatives Öffnen ausführen, indem FILE_WRITE_DATA angefordert wird | 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 breitstelligen Zeichenfolge, die den neuen Namen für die Datei enthält. Dies folgt im Arbeitsspeicher durch den Rest der Zeichenfolge. Wenn das RootDirectory Member 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 gibt sie nur den Dateinamen oder einen relativen Pfadnamen an.
Bemerkungen
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 als FILE_RENAME_INFORMATION Struktur formatierten Aufruferpuffer für den Wert FileInformation. 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 FltSetInformationFileverwenden, nicht ZwSetInformationFile-, um eine Datei umzubenennen.
Das Umbenennen einer Datei erfordert DELETE-Zugriff auf die Datei, sodass der Verzeichniseintrag aus dem aktuellen übergeordneten Verzeichnis entfernt werden kann, sowie den entsprechenden Zugriff, um den neuen Eintrag in der neuen übergeordneten Verzeichnisdatei zu erstellen.
Die Dateinamenzeichenfolge in der FileName Member muss in einem der folgenden Formulare angegeben werden.
Ein einfacher Dateiname. (Das RootDirectory Member 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 den Speicherort.
Ein vollqualifizierter Dateiname. (Das RootDirectory Member ist NULL.) In diesem Fall ändert der Umbenennungsvorgang den Namen und speicherort der Datei.
Ein relativer Dateiname. In diesem Fall enthält das RootDirectory Member 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. Mit anderen Worten, 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.
Auch wenn ReplaceIfExists auf TRUE festgelegt ist, schlägt der Umbenennungsvorgang immer noch fehl, wenn eine Datei mit demselben Namen bereits vorhanden ist und ein Verzeichnis, eine schreibgeschützte Datei oder eine aktuell ausgeführte Datei ist.
Dateien und Verzeichnisse eines Volumes können nicht umbenannt werden, wenn es sich bei dem Volume um ein schreibgeschütztes Volume handelt, z. B. ein CDFS-Volume oder ein schreibgeschütztes NTFS-Volume.
Spezielle Regeln zum 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 opportunistischen Batchsperre (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 offene Handles aufweist (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 (mit Ausnahme des weiter oben beschriebenen Batch-Oplock-Falls).
Spezielle Regeln zum Umbenennen von NTFS-Datenströmen:
Der Standardverzeichnisdatenstrom kann nicht umbenannt werden.
Der neue Name für den Datenstrom muss mit einem Doppelpunkt (:)) beginnen.
Ein Datenstrom kann nur in 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, wird der Umbenennungsvorgang nur erfolgreich ausgeführt, wenn ein Datenstrom mit demselben Namen nicht vorhanden ist oder ein Datenstrom der Länge Null ist.
"Umbenennen" des Standarddatenstroms ist zulässig, dies ist jedoch keine echte Umbenennung, da der Standarddatenstrom der Länge null hinterlässt.
Die Größe des FileInformation- Puffers, der an ZwSetInformationFile oder FltSetInformationFile übergeben wird, muss >= Sizeof(FILE_RENAME_INFORMATION) und die Größe in Byte der FileName Zeichenfolge sein.
Anforderungen
| Anforderung | Wert |
|---|---|
| Header- | ntifs.h (einschließlich Ntifs.h, Fltkernel.h) |