CopyFileExA 函式（winbase.h）

發行項
11/20/2024

將現有的檔案複製到新的檔案，並透過回呼函式通知其進度。

若要以交易作業的形式執行這項作業，請使用 CopyFileTransacted 函式。

語法

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

參數

[in] lpExistingFileName

現有檔案的名稱。

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

提示

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

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

[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_ALLOW_DECRYPTED_DESTINATION 0x00000008	即使無法加密目的地複本，嘗試複製加密的檔案仍會成功。
COPY_FILE_COPY_SYMLINK 0x00000800	如果來源檔案是符號連結，目的地檔案也是指向來源符號連結所指向之相同檔案的符號連結。 Windows Server 2003 和 Windows XP：不支援此值。
COPY_FILE_FAIL_IF_EXISTS 0x00000001	如果目標檔案已經存在，複製作業會立即失敗。
COPY_FILE_NO_BUFFERING 0x00001000	複製作業是使用未壓縮的 I/O 來執行，略過系統 I/O 快取資源。建議用於非常大的檔案傳輸。 Windows Server 2003 和 Windows XP：不支援此值。
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	檔案會複製並開啟源檔以進行寫入存取。
COPY_FILE_RESTARTABLE 0x00000002	複製的進度會在目標檔案中追蹤，以防複製失敗。失敗的復本可以在稍後重新啟動，方法是為失敗的呼叫中所使用的值指定相同的值 lpExistingFileName，並 lpNewFileName。這可能會大幅降低複製作業的速度，因為新檔案可能會在複製作業期間多次排清。
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	要求基礎傳輸通道在複製作業期間壓縮數據。所有媒體都可能不支援要求，在此情況下會予以忽略。壓縮屬性和參數（計算複雜度、記憶體使用量）無法透過此 API 設定，而且可能會在不同的 OS 版本之間變更。此旗標是在 Windows 10 版本 1903 和 Windows Server 2022 中引進的。在 Windows 10 上，SMB 共用上的檔案支援旗標，其中交涉 SMB 通訊協定版本為 SMB v3.1.1 或更新版本。

傳回值

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

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

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

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

言論

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

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

現有檔案的安全性資源屬性（ATTRIBUTE_SECURITY_INFORMATION）會複製到新檔案。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：現有檔案的安全性資源屬性在 Windows 8 和 Windows Server 2012 之前不會複製到新檔案。

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

當使用 CopyFileEx複製加密檔案時，函式會嘗試使用來源檔案加密中使用的密鑰來加密目的地檔案。如果無法這麼做，此函式會嘗試使用預設密鑰來加密目的地檔案。如果這兩種方法都無法完成，CopyFileEx 會失敗，並出現 ERROR_ENCRYPTION_FAILED 錯誤碼。如果您想要 CopyFileEx 完成複製作業，即使目的地檔案無法加密，請在呼叫 copyFileEx時，包含 COPY_FILE_ALLOW_DECRYPTED_DESTINATION 作為 dwCopyFlags 參數的值。

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

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

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

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

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：如果您要撰寫的應用程式，以優化跨 LAN 的檔案複製作業，請考慮使用 windows Sockets （Winsock）的 TransmitFile 函式。 TransmitFile 支援高效能網路傳輸，並提供簡單的介面，將檔案的內容傳送到遠端電腦。若要使用 TransmitFile，您必須撰寫 Winsock 用戶端應用程式，以從來源電腦傳送檔案，以及使用其他 Winsock 函式接收遠端電腦上的檔案的 Winsock 伺服器應用程式。

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

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

注意

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

要求

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