CopyFile2 函式 (winbase.h)
將現有的檔案複製到新檔案，並透過回呼函式通知其進度。
語法
HRESULT CopyFile2(
[in] PCWSTR pwszExistingFileName,
[in] PCWSTR pwszNewFileName,
[in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);
參數
[in] pwszExistingFileName
現有檔案的名稱。
若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\？」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 回 。
[in] pwszNewFileName
新檔案的名稱。
若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\？」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
[in, optional] pExtendedParameters
COPYFILE2_EXTENDED_PARAMETERS結構的選擇性位址。
傳回值
如果函式成功，傳回值會在傳遞至SUCCEEDED宏時傳回TRUE。
| 傳回碼 | 描述 |
|---|---|
|
複製作業已順利完成。 |
|
複製作業已由從CopyFile2ProgressRoutine回呼函式傳回的COPYFILE2_PROGRESS_PAUSE暫停。 |
|
複製作業已由copyFile2ProgressRoutine回呼函式的COPYFILE2_PROGRESS_CANCEL或COPYFILE2_PROGRESS_STOP暫停。 |
|
透過pExtendedParameters參數傳遞之COPYFILE2_EXTENDED_PARAMETERS結構的dwCopyFlags成員包含COPY_FILE_FAIL_IF_EXISTS旗標，並存在衝突的名稱。 |
|
透過pExtendedParameters參數傳遞之COPYFILE2_EXTENDED_PARAMETERS結構的dwCopyFlags成員包含COPY_FILE_FAIL_IF_EXISTS旗標，並存在衝突的名稱。 |
備註
此函式會保留擴充屬性、OLE 結構化儲存體、NTFS 檔案系統替代資料流程和檔案屬性。 現有檔案的安全性屬性不會複製到新檔案。 若要複製安全性屬性，請使用 SHFileOperation 函式。
如果目的地檔案已經存在，且已設定FILE_ATTRIBUTE_HIDDEN或FILE_ATTRIBUTE_READONLY屬性，此函式就會失敗 HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) 。
若要編譯使用此函式的應用程式，請將 _WIN32_WINNT 巨集定義為 _WIN32_WINNT_WIN8 或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器訊息區 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明容錯移轉 (TFO) | 是 |
| 具有向外延展檔案共用的 SMB 3.0 (SO) | 是 |
| 叢集共用磁片區檔案系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | Yes |
從 Windows 10 1903 版和 Windows Server 2022 版開始，此函式所傳遞之 COPYFILE2_EXTENDED_PARAMETERS結構的dwCopyFlags欄位支援新的值COPY_FILE_REQUEST_COMPRESSED_TRAFFIC。 這個新值會要求基礎傳輸通道在複製作業期間壓縮資料。 所有媒體都可能不支援要求，在此情況下會予以忽略。 壓縮屬性和參數 (計算複雜度、記憶體使用量) 無法透過此 API 設定，而且可能會在不同的 OS 版本之間變更。 在Windows 10上，SMB 共用上的檔案支援旗標，其中交涉的 SMB 通訊協定版本為 SMB v3.1.1 或更新版本。
規格需求
| 最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |