CopyFileTransactedA 函式（winbase.h）

發行項
11/20/2024

[Microsoft強烈建議開發人員利用替代方法來達成應用程式的需求。 TxF 開發的許多案例都可以透過更簡單且更容易使用的技術來達成。此外，未來版本的 Microsoft Windows 可能無法使用 TxF。如需詳細資訊和 TxF 的替代方案，請參閱使用交易式 NTFS的替代專案。

將現有檔案複製到新檔案做為交易作業，透過回呼函式通知其進度。

語法

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
);

參數

[in] lpExistingFileName

現有檔案的名稱。

根據預設，名稱限製為MAX_PATH個字元。若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。>。

如果 lpExistingFileName 不存在，CopyFileTransacted 函式會失敗，而 getLastError 函式會傳回 ERROR_FILE_NOT_FOUND。

檔案必須位於本機計算機上;否則，函式會失敗，且最後一個錯誤碼會設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。

[in] lpNewFileName

新檔案的名稱。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in, optional] lpProgressRoutine

每次複製檔案另一個部分時，呼叫類型為 LPPROGRESS_ROUTINE 的回呼函式位址。此參數可以是 NULL。如需進度回呼函式的詳細資訊，請參閱 CopyProgressRoutine 函式。

[in, optional] lpData

要傳遞至回呼函式的自變數。此參數可以是 NULL。

[in, optional] pbCancel

如果此旗標設定為在複製作業期間 TRUE，則會取消作業。否則，複製作業將會繼續完成。

[in] dwCopyFlags

指定要如何複製檔案的旗標。此參數可以是下列值的組合。

價值	意義
COPY_FILE_COPY_SYMLINK 0x00000800	如果來源檔案是符號連結，目的地檔案也是指向來源符號連結所指向之相同檔案的符號連結。
COPY_FILE_FAIL_IF_EXISTS 0x00000001	如果目標檔案已經存在，複製作業會立即失敗。
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	檔案會複製並開啟源檔以進行寫入存取。
COPY_FILE_RESTARTABLE 0x00000002	複製的進度會在目標檔案中追蹤，以防複製失敗。失敗的復本可以在稍後重新啟動，方法是為失敗的呼叫中所使用的值指定相同的值 lpExistingFileName，並 lpNewFileName。這可能會大幅降低複製作業的速度，因為新檔案可能會在複製作業期間多次排清。

[in] hTransaction

交易的句柄。此句柄是由 createTransaction 函式傳回。

傳回值

如果函式成功，則傳回值為非零值。

如果函式失敗，傳回值為零。若要取得擴充錯誤資訊呼叫，GetLastError。

如果 lpProgressRoutine 因為使用者取消作業而傳回 PROGRESS_CANCEL，CopyFileTransacted 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。在此情況下，會刪除部分複製的目的地檔案。

如果 lpProgressRoutine 因為使用者停止作業而傳回 PROGRESS_STOP，CopyFileTransacted 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。在此情況下，部分複製的目的地檔案會保持不變。

如果您嘗試使用已回覆之交易的句柄呼叫此函式，CopyFileTransacted 會傳回 ERROR_TRANSACTION_NOT_ACTIVE 或 ERROR_INVALID_TRANSACTION。

言論

此函式會保留擴充屬性、OLE 結構化記憶體、NTFS 檔案系統替代數據流、安全性屬性和檔案屬性。

Windows 7、Windows Server 2008 R2、Windows Server 2008 和 Windows Vista：現有檔案的安全性資源屬性（ATTRIBUTE_SECURITY_INFORMATION），直到 Windows 8 和 Windows Server 2012 才會複製到新檔案。

如果目的地檔案已經存在，且已設定 FILE_ATTRIBUTE_HIDDEN 或 FILE_ATTRIBUTE_READONLY 屬性，則此函式會失敗並 ERROR_ACCESS_DENIED。

TxF 不支援加密的檔案。

如果指定 COPY_FILE_COPY_SYMLINK，則會套用下列規則：

如果來源檔案是符號連結，則會複製符號連結，而不是目標檔案。
如果來源檔案不是符號連結，則行為沒有變更。
如果目的地檔案是現有的符號連結，則會覆寫符號連結，而不是目標檔案。
如果同時指定 COPY_FILE_FAIL_IF_EXISTS，而且目的地檔案是現有的符號連結，則作業在所有情況下都會失敗。

如果未指定 COPY_FILE_COPY_SYMLINK，則會套用下列規則：

如果同時指定 COPY_FILE_FAIL_IF_EXISTS，而且目的地檔案是現有的符號連結，則只有在符號鏈接的目標存在時，作業才會失敗。
如果未指定 COPY_FILE_FAIL_IF_EXISTS，則行為沒有變更。

TxF 不支持連結追蹤。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	不
SMB 3.0 透明故障轉移（TFO）	不
具有向外延展檔案共用的SMB 3.0（SO）	不
叢集共用磁碟區檔案系統（CsvFS）	不
復原檔案系統（ReFS）	不

請注意，SMB 3.0 不支援 TxF。

注意

winbase.h 標頭會根據 UNICODE 預處理器常數的定義，將 CopyFileTransacted 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winbase.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll