copyFileTransactedA 函式 (winbase.h)

發行項
06/02/2023

[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：在Windows 8和Windows Server 2012之前，不會將現有檔案的安全性資源屬性 (ATTRIBUTE_SECURITY_INFORMATION) 複製到新檔案。

如果目的地檔案已經存在，且已設定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 通訊協定	No
SMB 3.0 透明容錯移轉 (TFO)	No
具有向外延展檔案共用的 SMB 3.0 (SO)	No
叢集共用磁片區檔案系統 (CsvFS)	No
彈性檔案系統 (ReFS)	No

請注意，SMB 3.0 不支援 TxF。

注意

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

規格需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll