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

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

值 意義
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： 在 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_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 的 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

另請參閱

CopyFile

CopyFileTransacted

CopyProgressRoutine

CreateFile

檔案屬性常數

檔案管理功能

MoveFile

MoveFileWithProgress

符號連結

TransmitFile