CopyFile2 函式 (winbase.h)

  • 發行項

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

語法

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

參數

[in] pwszExistingFileName

現有檔案的名稱。

若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\？」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示從 Windows 10 1607 版開始，您可以選擇移除MAX_PATH字元限制，而不需在前面加上 「\\？\」。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的「路徑限制上限」一節。
 
如果 lpExistingFileName 不存在， CopyFile2 函式會失敗傳 HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 回 。

[in] pwszNewFileName

新檔案的名稱。

若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\？」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示從 Windows 10 1607 版開始，您可以選擇移除MAX_PATH字元限制，而不需在前面加上 「\\？\」。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的「路徑限制上限」一節。
 

[in, optional] pExtendedParameters

COPYFILE2_EXTENDED_PARAMETERS結構的選擇性位址。

傳回值

如果函式成功，傳回值會在傳遞至SUCCEEDED宏時傳回TRUE。

傳回碼 描述
S_OK
 複製作業已順利完成。
HRESULT_FROM_WIN32 (ERROR_REQUEST_PAUSED)
複製作業已由從CopyFile2ProgressRoutine回呼函式傳回的COPYFILE2_PROGRESS_PAUSE暫停。
HRESULT_FROM_WIN32 (ERROR_REQUEST_ABORTED)
複製作業已由copyFile2ProgressRoutine回呼函式的COPYFILE2_PROGRESS_CANCEL或COPYFILE2_PROGRESS_STOP暫停。
HRESULT_FROM_WIN32 (ERROR_ALREADY_EXISTS)
透過pExtendedParameters參數傳遞之COPYFILE2_EXTENDED_PARAMETERS結構的dwCopyFlags成員包含COPY_FILE_FAIL_IF_EXISTS旗標，並存在衝突的名稱。
HRESULT_FROM_WIN32 (ERROR_FILE_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

另請參閱

COPYFILE2_EXTENDED_PARAMETERS

檔案管理功能