MoveFileTransactedW-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 MoveFileTransactedW(
  [in]           LPCWSTR            lpExistingFileName,
  [in, optional] LPCWSTR            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 vorhandenen Verzeichnisses auf dem lokalen Computer.

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 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 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. Der Im Abschnitt Hinweise beschriebene Schreibvorgang in den Registrierungswert wird abgewickelt. 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 benennen.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Ein Aufruf von MoveFileTransacted bedeutet, dass der Vorgang zum Verschieben der Datei abgeschlossen ist, wenn der Commitvorgang abgeschlossen ist. Dieses Flag ist nicht erforderlich. Es gibt keine negativen Auswirkungen, wenn dieses Flag angegeben wird, außer einer Vorgangsverlangsamung. 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 auf 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 auf Volumes PROGRESS_STOP zurückgibt, weil der Benutzer den Vorgang beendet hat, 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, 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. Weitere Informationen zur Verwendung des MOVEFILE_DELAY_UNTIL_REBOOT-Flags finden Sie unter MoveFileWithProgress.

Wenn eine Datei auf Volumes verschoben wird, verschob 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 (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

CopyFileTransacted

Dateiverwaltungsfunktionen

MoveFileWithProgress

Transaktions-NTFS

Freigeben über