MoveFileTransactedA-Funktion (winbase.h)

Artikel
03/03/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu verwenden, um die Anforderungen Ihrer Anwendung zu erfüllen. Viele Szenarios, für die TxF entwickelt wurde, können mit einfacheren und leichter verfügbaren Techniken erreicht werden. Darüber hinaus ist TxF in zukünftigen Versionen von Microsoft Windows möglicherweise nicht verfügbar. Weitere Informationen und Alternativen zu TxF finden Sie unter Alternativen zur Verwendung von transaktionalem NTFS.]

Verschiebt eine vorhandene Datei oder ein Verzeichnis, einschließlich der untergeordneten Elemente, als Transaktionsvorgang.

Syntax

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

Parameter

[in] lpExistingFileName

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

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 für die Datei oder das Verzeichnis. Der neue Name darf noch nicht vorhanden sein. Eine neue Datei kann sich auf einem anderen Dateisystem oder Laufwerk befinden. Ein neues Verzeichnis muss sich auf demselben Laufwerk befinden.

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. Der Schreibvorgang in den Registrierungswert, wie im Abschnitt Hinweise beschrieben, wird ausgeführt. Die Dateiverschiebung ist abgeschlossen, wenn der Computer neu gestartet wird, nachdem die Transaktion abgeschlossen 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)	Ein Aufruf von MoveFileTransacted bedeutet, dass der Dateiverschiebungsvorgang abgeschlossen ist, wenn der Commitvorgang abgeschlossen ist. Diese Kennzeichnung ist unnötig; Es gibt keine negativen Auswirkungen, wenn dieses Flag angegeben wird, außer einer Verlangsamung des Vorgangs. 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.

[in] hTransaction

Ein Handle für die Transaktion. Dieses Handle wird von der CreateTransaction-Funktion zurückgegeben.

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 zwischen Volumes PROGRESS_CANCEL zurückgibt, weil der Benutzer den Vorgang abgebrochen hat, gibt MoveFileTransacted 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 MoveFileTransacted null zurück, und GetLastError gibt ERROR_REQUEST_ABORTED zurück. Die vorhandene Datei bleibt intakt.

Hinweise

Wenn der dwFlags-ParameterMOVEFILE_DELAY_UNTIL_REBOOT angibt, schlägt MoveFileTransacted fehl, wenn es nicht auf die Registrierung zugreifen kann. Die Funktion speichert die Speicherorte der Dateien, die beim Neustart umbenannt werden sollen, transaktional 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 darauf zurückzuführen sein, dass die Datei in einen NULL-Namen umbenannt wird.

Das System verwendet diese Registrierungseinträge, um die Vorgänge beim Neustart in derselben Reihenfolge abzuschließen, in der sie ausgestellt wurden. Weitere Informationen zur Verwendung des MOVEFILE_DELAY_UNTIL_REBOOT-Flags finden Sie unter MoveFileWithProgress.

Wenn eine Datei über Volumes verschoben wird, verschet MoveFileTransacted den Sicherheitsdeskriptor nicht mit der Datei. Der Datei wird der Standardsicherheitsdeskriptor im Zielverzeichnis zugewiesen.

Diese Funktion schlägt immer fehl, wenn Sie das flag MOVEFILE_FAIL_IF_NOT_TRACKABLE angeben. Die Nachverfolgung wird von TxF nicht unterstützt.

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)	No
SMB 3.0 Transparent Failover (TFO)	No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	No
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	No
Robustes Dateisystem (Resilient File System, ReFS)	No

SMB 3.0 unterstützt TxF nicht.

Anforderungen

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

Siehe auch

CopyFileTransacted

Dateiverwaltungsfunktionen

MoveFileWithProgress

Transaktions-NTFS