MoveFileExW-Funktion (winbase.h)

Artikel
03/06/2024

Verschiebt eine vorhandene Datei oder ein vorhandenes Verzeichnis, einschließlich der untergeordneten Elemente, mithilfe verschiedener Verschiebungsoptionen.

Die MoveFileWithProgress-Funktion entspricht der MoveFileEx-Funktion , mit der Ausnahme, dass Sie mit MoveFileWithProgress eine Rückruffunktion bereitstellen können, die Statusbenachrichtigungen empfängt.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die MoveFileTransacted-Funktion .

Syntax

BOOL MoveFileExW(
  [in]           LPCWSTR lpExistingFileName,
  [in, optional] LPCWSTR lpNewFileName,
  [in]           DWORD   dwFlags
);

Parameter

[in] lpExistingFileName

Der aktuelle Name der Datei oder des Verzeichnisses auf dem lokalen Computer.

Wenn dwFlagsMOVEFILE_DELAY_UNTIL_REBOOT angibt, kann die Datei nicht auf einer Remotefreigabe vorhanden sein, da verzögerte Vorgänge ausgeführt werden, bevor das Netzwerk verfügbar ist.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

[in, optional] lpNewFileName

Der neue Name der Datei oder des Verzeichnisses auf dem lokalen Computer.

Beim Verschieben einer Datei kann sich das Ziel auf einem anderen Dateisystem oder Volume befinden. Wenn sich das Ziel auf einem anderen Laufwerk befindet, müssen Sie das MOVEFILE_COPY_ALLOWED-Flag in dwFlags festlegen.

Beim Verschieben eines Verzeichnisses muss sich das Ziel auf demselben Laufwerk befinden.

Wenn dwFlagsangibt, MOVEFILE_DELAY_UNTIL_REBOOT und lpNewFileNameNULL ist, registriert MoveFileEx die LpExistingFileName-Datei , um beim Neustart des Systems gelöscht zu werden. Wenn lpExistingFileName auf ein Verzeichnis verweist, entfernt das System das Verzeichnis beim Neustart nur, wenn das Verzeichnis leer ist.

In der ANSI-Version dieser Funktion ist der Name auf MAX_PATH Zeichen beschränkt. Um diese Grenze auf 32.767 Breite Zeichen zu erweitern, rufen Sie die Unicode-Version der Funktion auf, und stellen Sie dem Pfad "\?" voran. Weitere Informationen finden Sie unter Benennen einer Datei.

Tipp

[in] dwFlags

Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
MOVEFILE_COPY_ALLOWED 2 (0x2)	Wenn die Datei auf ein anderes Volume verschoben werden soll, simuliert die Funktion die Verschiebung mithilfe der Funktionen CopyFile und DeleteFile . Wenn die Datei erfolgreich auf ein anderes Volume kopiert wurde und die ursprüngliche Datei nicht gelöscht werden kann, kann die Funktion erfolgreich die Quelldatei intakt lassen. Dieser Wert kann nicht mit MOVEFILE_DELAY_UNTIL_REBOOT verwendet werden.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Für die zukünftige Verwendung reserviert.
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	Das System verschet die Datei erst, wenn das Betriebssystem neu gestartet wird. Das System verschiebt die Datei unmittelbar nach der Ausführung von AUTOCHK, aber vor dem Erstellen von Auslagerungsdateien. Folglich ermöglicht dieser Parameter der Funktion das Löschen von Pagingdateien aus früheren Startups. Dieser Wert kann nur verwendet werden, wenn sich der Prozess im Kontext eines Benutzers befindet, der der Administratorgruppe oder dem LocalSystem-Konto angehört. Dieser Wert kann nicht mit MOVEFILE_COPY_ALLOWED verwendet werden.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	Die Funktion schlägt fehl, wenn es sich bei der Quelldatei um eine Linkquelle handelt, aber die Datei kann nach der Verschiebung nicht nachverfolgt werden. Diese Situation kann auftreten, wenn das Ziel ein Volume ist, das mit dem FAT-Dateisystem formatiert ist.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Wenn eine Datei mit dem Namen lpNewFileName vorhanden ist, ersetzt die Funktion ihren Inhalt durch den Inhalt der LpExistingFileName-Datei , sofern die Sicherheitsanforderungen für Zugriffssteuerungslisten (Access Control Lists, ACLs) erfüllt sind. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“. Wenn lpNewFileName ein vorhandenes Verzeichnis benennt, wird ein Fehler gemeldet.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Die Funktion wird erst zurückgegeben, wenn die Datei tatsächlich auf dem Datenträger verschoben wird. Durch Festlegen dieses Werts wird sichergestellt, dass eine als Kopier- und Löschvorgang ausgeführte Verschiebung auf den Datenträger geleert wird, bevor die Funktion zurückgegeben wird. Die Leerung erfolgt am Ende des Kopiervorgangs. Dieser Wert hat keine Auswirkung, wenn MOVEFILE_DELAY_UNTIL_REBOOT festgelegt ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der dwFlags-ParameterMOVEFILE_DELAY_UNTIL_REBOOT angibt, schlägt MoveFileEx fehl, wenn es nicht auf die Registrierung zugreifen kann. Die Funktion speichert die Speicherorte der Dateien, die beim Neustart umbenannt werden sollen, im folgenden Registrierungswert: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

Dieser Registrierungswert ist vom Typ REG_MULTI_SZ. Jeder Umbenennungsvorgang speichert eine der folgenden NULL-beendeten Zeichenfolgen, je nachdem, ob die Umbenennung ein Löschvorgang ist oder nicht:

szDstFile\0\0
szSrcFile\0szDstFile\0

Die Zeichenfolge szDstFile\0\0 gibt an, dass die Datei szDstFile beim Neustart gelöscht werden soll. Die Zeichenfolge szSrcFile\0szDstFile\0 gibt an, dass szSrcFile beim Neustart in szDstFile umbenannt werden soll.

Hinweis Obwohl \0\0 in einem REG_MULTI_SZ Knoten technisch nicht zulässig ist, kann dies möglich sein, da die Datei als in einen NULL-Namen umbenannt wird.

Das System verwendet diese Registrierungseinträge, um die Vorgänge beim Neustart in der gleichen Reihenfolge abzuschließen, in der sie ausgestellt wurden. Das folgende Codefragment erstellt beispielsweise Registrierungseinträge, die szDstFile löschen und szSrcFile beim Neustart in szDstFile umbenennen:

MoveFileEx(szDstFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

Da die tatsächlichen Verschiebungs- und Löschvorgänge, die mit dem MOVEFILE_DELAY_UNTIL_REBOOT-Flag angegeben werden, erfolgen, nachdem die aufrufende Anwendung nicht mehr ausgeführt wurde, kann der Rückgabewert keinen Erfolg oder Fehler beim Verschieben oder Löschen der Datei widerspiegeln. Es spiegelt vielmehr den Erfolg oder Fehler beim Platzieren der entsprechenden Einträge in der Registrierung wider.

Das System löscht ein Verzeichnis, das zum Löschen mit dem flag MOVEFILE_DELAY_UNTIL_REBOOT markiert ist, nur, wenn es leer ist. Um das Löschen von Verzeichnissen sicherzustellen, verschieben oder löschen Sie alle Dateien aus dem Verzeichnis, bevor Sie versuchen, es zu löschen. Dateien befinden sich möglicherweise zur Startzeit im Verzeichnis, müssen jedoch gelöscht oder verschoben werden, bevor das System das Verzeichnis löschen kann.

Die Verschiebungs- und Löschvorgänge werden zur Startzeit in der gleichen Reihenfolge ausgeführt wie in der aufrufenden Anwendung. Wenn Sie ein Verzeichnis löschen möchten, in dem dateien zur Startzeit enthalten sind, löschen Sie zuerst die Dateien.

Wenn eine Datei auf Volumes verschoben wird, verschob MoveFileEx den Sicherheitsdeskriptor nicht mit der Datei. Der Datei wird der Standardsicherheitsdeskriptor im Zielverzeichnis zugewiesen.

Die MoveFileEx-Funktion koordiniert ihren Vorgang mit dem Linkverfolgungsdienst , sodass Linkquellen beim Verschieben nachverfolgt werden können.

Um eine Datei zu löschen oder umzubenennen, müssen Sie entweder über die Löschberechtigung für die Datei oder über die untergeordnete Berechtigung im übergeordneten Verzeichnis verfügen. Wenn Sie ein Verzeichnis mit allen Zugriffen mit Ausnahme des untergeordneten Lösch- und Löschvorgangs einrichten und die ACLs neuer Dateien geerbt werden, sollten Sie in der Lage sein, eine Datei zu erstellen, ohne sie löschen zu können. Sie können dann jedoch eine Datei erstellen und den gesamten Zugriff erhalten, den Sie auf das Handle anfordern, das Ihnen zum Zeitpunkt der Erstellung der Datei zurückgegeben wird. Wenn Sie zum Zeitpunkt der Erstellung der Datei die Löschberechtigung anfordern, können Sie die Datei mit diesem Handle, aber nicht mit einem anderen Handle löschen oder umbenennen. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Beispiele

Ein Beispiel finden Sie unter Erstellen und Verwenden einer temporären Datei.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll