CopyFileExA 函式 (winbase.h)
將現有的檔案複製到新檔案，並透過回呼函式通知其進度。
若要以交易作業的形式執行此作業，請使用 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
新檔案的名稱。
根據預設，名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
提示
從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。
[in, optional] lpProgressRoutine
每次複製檔案另一個部分時呼叫的回呼函 式LPPROGRESS_ROUTINE位址 。 此參數可以是 Null。 如需進度回呼函式的詳細資訊，請參閱 CopyProgressRoutine 函式。
[in, optional] lpData
要傳遞至回呼函式的自變數。 此參數可以是 Null。
[in, optional] pbCancel
如果此旗標在複製作業期間設定為 TRUE ，則會取消作業。 否則，複製作業將會繼續完成。
[in] dwCopyFlags
指定要如何複製檔案的旗標。 此參數可以是下列值的組合。
傳回值
如果函式成功，則傳回非零的值。
如果此函式失敗，則傳回值為零。 若要取得擴充錯誤資訊，請呼叫 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： 在 Windows 8 和 Windows Server 2012 之前，不會將現有檔案的安全性資源屬性 (ATTRIBUTE_SECURITY_INFORMATION) 複製到新檔案。
將現有檔案的安全性資源屬性 (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_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 的 TransmitFile 函式 (Winsock) 。 TransmitFile 支援高效能的網路傳輸，並提供簡單的介面，將檔案的內容傳送至遠端電腦。 若要使用 TransmitFile，您必須撰寫從來源電腦傳送檔案的 Winsock 用戶端應用程式，以及使用其他 Winsock 函式接收遠端電腦上的檔案的 Winsock 伺服器應用程式。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器消息塊 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明故障轉移 (TFO) | Yes |
| 具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
| 叢集共用磁碟區文件系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | Yes |
注意
winbase.h 標頭會將 CopyFileEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |