MoveFileExA-Funktion (winbase.h)

Artikel
06/27/2024

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

Die MoveFileWithProgress--Funktion entspricht der MoveFileEx--Funktion, mit der Ausnahme, dass MoveFileWithProgress- es Ihnen ermöglicht, eine Rückruffunktion bereitzustellen, die Statusbenachrichtigungen empfängt.

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

Syntax

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

Parameter

[in] lpExistingFileName

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

Wenn dwFlagsMOVEFILE_DELAY_UNTIL_REBOOTangibt, kann die Datei nicht in 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 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 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 dwFlags-MOVEFILE_DELAY_UNTIL_REBOOT angibt und lpNewFileNameNULL-ist, registriert MoveFileEx die lpExistingFileName Datei, die beim Neustart des Systems gelöscht werden soll. Wenn lpExistingFileName auf ein Verzeichnis verweist, entfernt das System das Verzeichnis beim Neustart nur, wenn das Verzeichnis leer ist.

Trinkgeld

[in] dwFlags

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 datei lpExistingFileName, vorausgesetzt, die Sicherheitsanforderungen für Zugriffssteuerungslisten (ACCESS Control Lists, ACLs) sind erfüllt. Weitere Informationen finden Sie im Abschnitt "Hinweise" dieses Themas. 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 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 (0). Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

Dieser Registrierungswert ist vom Typ REG_MULTI_SZ. Jeder Umbenennungsvorgang speichert eine der folgenden MIT NULL beendeten Zeichenfolgen, je nachdem, ob es sich bei der Umbenennung um einen Löschvorgang handelt oder nicht:

szSrcFile\0\0
szSrcFile\0szDstFile\0

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

Hinweis Obwohl \0\0 technisch nicht in einem REG_MULTI_SZ Knoten zulässig ist, kann die Datei als in einen Nullnamen umbenannt werden.

Das System verwendet diese Registrierungseinträge, um die Vorgänge beim Neustart in derselben Reihenfolge abzuschließen, in der sie ausgegeben wurden. Beispielsweise erstellt das folgende Codefragment Registrierungseinträge, die szSrcFile löschen und szSrcFile umbenennen, um beim Neustart szDstFile zu werden:

MoveFileEx(szSrcFile, 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 wurden, nach beendigung der Ausführung der aufrufenden Anwendung stattfinden, kann der Rückgabewert nicht erfolg- oder fehler beim Verschieben oder Löschen der Datei entsprechen. Vielmehr spiegelt sie Erfolg oder Fehler bei der Platzierung der entsprechenden Einträge in die Registrierung wider.

Das System löscht ein Verzeichnis, das zum Löschen mit dem MOVEFILE_DELAY_UNTIL_REBOOT Flag gekennzeichnet ist, nur, wenn es leer ist. Um sicherzustellen, dass Verzeichnisse gelöscht werden, verschieben oder löschen Sie alle Dateien aus dem Verzeichnis, bevor Sie versuchen, sie 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 derselben Reihenfolge ausgeführt, in der sie in der aufrufenden Anwendung angegeben sind. Wenn Sie ein Verzeichnis löschen möchten, in dem dateien zur Startzeit enthalten sind, löschen Sie zuerst die Dateien.

Wenn eine Datei über Volumes verschoben wird, wird MoveFileEx- die Sicherheitsbeschreibung nicht mit der Datei verschieben. Die Datei wird dem Standardsicherheitsdeskriptor im Zielverzeichnis zugewiesen.

Die MoveFileEx--Funktion koordiniert ihren Vorgang mit dem Linkverfolgung Dienst, sodass Linkquellen nachverfolgt werden können, während 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 alle Zugriffe erhalten, die Sie für das Handle anfordern, das zum Zeitpunkt der Erstellung der Datei an Sie zurückgegeben wird. Wenn Sie zum Zeitpunkt der Erstellung der Datei die Löschberechtigung anfordern, können Sie die Datei mit diesem Handle löschen oder umbenennen, aber nicht mit einem anderen Handle. Weitere Informationen finden Sie unter Dateisicherheits- und Zugriffsberechtigungen.

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

Beispiele

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll