MoveFileWithProgressA-Funktion (winbase.h)

Artikel
06/02/2023

Verschiebt eine Datei oder ein Verzeichnis, einschließlich der untergeordneten Elemente. Sie können eine Rückruffunktion bereitstellen, die Statusbenachrichtigungen empfängt.

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

Syntax

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

Parameter

[in] lpExistingFileName

Der Name der vorhandenen 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 diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. 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 aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen 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 lpNewFileName auf einem anderen Dateisystem oder Volume befinden. Wenn sich lpNewFileName auf einem anderen Laufwerk befindet, müssen Sie das flag MOVEFILE_COPY_ALLOWED in dwFlags festlegen.

Beim Verschieben eines Verzeichnisses müssen sich lpExistingFileName und lpNewFileName auf demselben Laufwerk befinden.

Wenn dwFlagsMOVEFILE_DELAY_UNTIL_REBOOT angibt und lpNewFileNameNULL ist, registriert MoveFileWithProgresslpExistingFileName , um beim Neustart des Systems gelöscht zu werden. Die Funktion schlägt fehl, wenn sie nicht auf die Registrierung zugreifen kann, um die Informationen zum Löschvorgang zu speichern. Wenn lpExistingFileName auf ein Verzeichnis verweist, entfernt das System das Verzeichnis beim Neustart nur, wenn das Verzeichnis leer ist.

Tipp

[in, optional] lpProgressRoutine

Ein Zeiger auf eine CopyProgressRoutine-Rückruffunktion , die jedes Mal aufgerufen wird, wenn ein anderer Teil der Datei verschoben wurde. Die Rückruffunktion kann nützlich sein, wenn Sie eine Benutzeroberfläche bereitstellen, die den Fortschritt des Vorgangs anzeigt. Dieser Parameter kann NULL sein.

[in, optional] lpData

Ein Argument, das an die Rückruffunktion CopyProgressRoutine übergeben werden soll. Dieser Parameter kann NULL sein.

[in] dwFlags

Die Verschiebungsoptionen. 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 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 verschenkt 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, die Datei aber nach dem Verschieben nicht nachverfolgt werden kann. 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 . Dieser Wert kann nicht verwendet werden, wenn lpNewFileName oder lpExistingFileName ein Verzeichnis benennt.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Die Funktion wird erst zurückgegeben, wenn die Datei tatsächlich auf dem Datenträger verschoben wurde. 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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn lpProgressRoutine beim Verschieben einer Datei auf Volumes PROGRESS_CANCEL zurückgibt, weil der Benutzer den Vorgang abgebrochen hat, gibt MoveFileWithProgress null zurück, und GetLastError gibt ERROR_REQUEST_ABORTED zurück. Die vorhandene Datei bleibt intakt.

Wenn lpProgressRoutine beim Verschieben einer Datei über Volumes hinweg PROGRESS_STOP zurückgibt, weil der Benutzer den Vorgang beendet, gibt MoveFileWithProgress null zurück, und GetLastError gibt ERROR_REQUEST_ABORTED zurück. Die vorhandene Datei bleibt intakt.

Hinweise

Die MoveFileWithProgress-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 Berechtigung zum Löschen der Datei oder über die berechtigung "Untergeordnetes Löschen" im übergeordneten Verzeichnis verfügen. Wenn Sie ein Verzeichnis mit allen Zugriffen einrichten, mit Ausnahme des untergeordneten Lösch- und Löschvorgangs, und die ACLs neuer Dateien werden geerbt, sollten Sie eine Datei erstellen können, ohne sie löschen zu können. Sie können dann jedoch eine Datei erstellen, und Sie erhalten den gesamten Zugriff, den Sie zum Zeitpunkt der Erstellung der Datei an das Handle anfordern. Wenn Sie zum Zeitpunkt der Erstellung der Datei die Löschberechtigung angefordert haben, können Sie die Datei mit diesem Handle löschen oder umbenennen, aber nicht mit einem anderen.

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

CsvFs leiten E/A für komprimierte Dateien um.

Hinweis

Der winbase.h-Header definiert MoveFileWithProgress als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

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

Siehe auch

CopyFileEx

CopyProgressRoutine

Dateiverwaltungsfunktionen

MoveFileEx

MoveFileTransacted