CopyFileTransactedA-Funktion (winbase.h)

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu verwenden, um die Anforderungen Ihrer Anwendung zu erfüllen. Viele Szenarien, für die TxF entwickelt wurde, können durch einfachere und leichter verfügbare 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 Transaktions-NTFS.]

Kopiert eine vorhandene Datei als transaktionierten Vorgang in eine neue Datei, wobei die Anwendung über eine Rückruffunktion über den Fortschritt benachrichtigt wird.

Syntax

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

Parameter

[in] lpExistingFileName

Der Name einer vorhandenen Datei.

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.

Wenn lpExistingFileName nicht vorhanden ist, schlägt die CopyFileTransacted-Funktion fehl, und die GetLastError-Funktion gibt ERROR_FILE_NOT_FOUND zurück.

Die Datei muss sich auf dem lokalen Computer befinden. Andernfalls schlägt die Funktion fehl, und der letzte Fehlercode ist auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE festgelegt.

[in] lpNewFileName

Der Name der neuen Datei.

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.

[in, optional] lpProgressRoutine

Die Adresse einer Rückruffunktion vom Typ LPPROGRESS_ROUTINE , die jedes Mal aufgerufen wird, wenn ein anderer Teil der Datei kopiert wurde. Dieser Parameter kann NULL sein. Weitere Informationen zur Statusrückruffunktion finden Sie in der CopyProgressRoutine-Funktion .

[in, optional] lpData

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

[in, optional] pbCancel

Wenn dieses Flag während des Kopiervorgangs auf TRUE festgelegt ist, wird der Vorgang abgebrochen. Andernfalls wird der Kopiervorgang weiterhin abgeschlossen.

[in] dwCopyFlags

Flags, die angeben, wie die Datei kopiert werden soll. Dieser Parameter kann eine Kombination der folgenden Werte sein.

[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. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Wenn lpProgressRoutinePROGRESS_CANCEL zurückgibt, weil der Benutzer den Vorgang abgebrochen hat, gibt CopyFileTransacted null zurück, und GetLastError gibt ERROR_REQUEST_ABORTED zurück. In diesem Fall wird die teilweise kopierte Zieldatei gelöscht.

Wenn lpProgressRoutinePROGRESS_STOP zurückgibt, weil der Benutzer den Vorgang beendet hat, gibt CopyFileTransacted null und GetLastErrorERROR_REQUEST_ABORTED zurück. In diesem Fall bleibt die teilweise kopierte Zieldatei intakt.

Wenn Sie versuchen, diese Funktion mit einem Handle für eine Transaktion aufzurufen, die bereits zurückgesetzt wurde, gibt CopyFileTransacted entweder ERROR_TRANSACTION_NOT_ACTIVE oder ERROR_INVALID_TRANSACTION zurück.

Bemerkungen

Diese Funktion behält erweiterte Attribute, strukturierte OLE-Speicher, alternative NTFS-Dateisystemdatenströme, Sicherheitsattribute und Dateiattribute bei.

Windows 7, Windows Server 2008 R2, Windows Server 2008 und Windows Vista: Sicherheitsressourcenattribute (ATTRIBUTE_SECURITY_INFORMATION) für die vorhandene Datei werden erst in die neue Datei kopiert, bis Windows 8 und Windows Server 2012.

Diese Funktion schlägt mit ERROR_ACCESS_DENIED fehl, wenn die Zieldatei bereits vorhanden ist und das attribut FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY festgelegt ist.

Verschlüsselte Dateien werden von TxF nicht unterstützt.

Wenn COPY_FILE_COPY_SYMLINK angegeben ist, gelten die folgenden Regeln:

• Wenn es sich bei der Quelldatei um einen symbolischen Link handelt, wird der symbolische Link kopiert, nicht die Zieldatei.
• Wenn die Quelldatei keine symbolische Verknüpfung ist, gibt es keine Verhaltensänderung.
• Wenn die Zieldatei ein vorhandener symbolischer Link ist, wird der symbolische Link überschrieben, nicht die Zieldatei.
• Wenn auch COPY_FILE_FAIL_IF_EXISTS angegeben ist und die Zieldatei ein vorhandener symbolischer Link ist, schlägt der Vorgang in allen Fällen fehl.

• Wenn auch COPY_FILE_FAIL_IF_EXISTS angegeben ist und die Zieldatei eine vorhandene symbolische Verknüpfung ist, schlägt der Vorgang nur fehl, wenn das Ziel der symbolischen Verknüpfung vorhanden ist.
• Wenn COPY_FILE_FAIL_IF_EXISTS nicht angegeben ist, gibt es keine Verhaltensänderung.

Die Linknachverfolgung wird von TxF nicht unterstützt.

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

Beachten Sie, dass SMB 3.0 TxF nicht unterstützt.

Anforderungen

Siehe auch

CopyProgressRoutine

CreateFileTransacted

Dateiattributekonstanten

Dateiverwaltungsfunktionen

MoveFileTransacted

Symbolische Links

Transaktions-NTFS