MoveFileWithProgressW-Funktion (winbase.h)

Artikel
11/20/2024

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

Verwenden Sie die MoveFileTransacted-Funktion, um diesen Vorgang als transacted-Vorgang auszuführen.

Syntax

BOOL MoveFileWithProgressW(
  [in]           LPCWSTR            lpExistingFileName,
  [in, optional] LPCWSTR            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_REBOOTangibt, kann die Datei nicht für eine 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 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Trinkgeld

Ab Windows 10, Version 1607, können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

[in, optional] lpNewFileName

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

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

Beim Verschieben eines Verzeichnisses müssen lpExistingFileName- und lpNewFileName- auf demselben Laufwerk sein.

Wenn dwFlagsMOVEFILE_DELAY_UNTIL_REBOOT angibt und lpNewFileName-NULL-ist, registriert MoveFileWithProgresslpExistingFileName gelöscht werden, wenn das System neu gestartet wird. 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.

Trinkgeld

[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 CopyProgressRoutine Rückruffunktion übergeben werden soll. Dieser Parameter kann NULL-sein.

[in] dwFlags

Die Verschiebungsoptionen. Dieser Parameter kann einen oder mehrere der folgenden Werte sein.

Wert	Bedeutung
MOVEFILE_COPY_ALLOWED 2 (0x2)	Wenn die Datei auf ein anderes Volume verschoben werden soll, simuliert die Funktion die Verschiebung mithilfe der CopyFile- und DeleteFile- Funktionen. 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 nicht beibehalten. Dieser Wert kann nicht mit MOVEFILE_DELAY_UNTIL_REBOOTverwendet werden.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Reserviert für die zukünftige Verwendung.
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	Das System verschebt 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 die Funktion das Löschen von Auslagerungsdateien aus früheren Startups. Dieser Wert kann nur verwendet werden, wenn sich der Prozess im Kontext eines Benutzers befindet, der zur Administratorgruppe oder zum LocalSystem-Konto gehört. Dieser Wert kann nicht mit MOVEFILE_COPY_ALLOWEDverwendet 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 der Verschiebung 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 Verschiebung, die als Kopier- und Löschvorgang ausgeführt wird, auf den Datenträger geleert wird, bevor die Funktion zurückgegeben wird. Die Spülung 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 null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Wenn lpProgressRoutine beim Verschieben einer Datei über Volumes hinweg PROGRESS_CANCEL zurückgibt, wenn der Benutzer den Vorgang abbricht, gibt MoveFileWithProgress Null zurück, und GetLastError- wird ERROR_REQUEST_ABORTEDzurückgegeben. Die vorhandene Datei bleibt erhalten.

Wenn lpProgressRoutine beim Verschieben einer Datei über Volumes hinweg PROGRESS_STOP aufgrund des Beendens des Vorgangs zurückgibt, gibt MoveFileWithProgress Null zurück, und "GetLastError"- wird ERROR_REQUEST_ABORTEDzurückgegeben. Die vorhandene Datei bleibt erhalten.

Bemerkungen

Die MoveFileWithProgress--Funktion koordiniert den Vorgang mit dem Linkverfolgungsdienst, sodass Linkquellen nachverfolgt werden können, sobald sie verschoben werden.

Um eine Datei zu löschen oder umzubenennen, müssen Sie entweder über die Berechtigung zum Löschen der Datei oder über die Berechtigung zum Löschen untergeordneter Elemente im übergeordneten Verzeichnis verfügen. Wenn Sie ein Verzeichnis mit allen Zugriffen mit Ausnahme des Löschens und Löschens untergeordneter Dateien einrichten und die ACLs neuer Dateien geerbt werden, 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 alle Zugriffe, die Sie beim Erstellen der Datei an Sie erhalten. 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 anderen.

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

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

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

Anmerkung

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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll

Siehe auch

CopyFileEx-

CopyProgressRoutine-

Dateiverwaltungsfunktionen

MoveFileEx-

MoveFileTransacted-

Freigeben über