CopyFileA 函式 (winbase.h)
複製現有的檔案到新的檔案。
CopyFileEx 函式提供兩個額外的功能。 CopyFileEx 可以在每次複製作業完成時呼叫指定的回呼函式,而 CopyFileEx 可以在複製作業期間取消。
若要以交易作業的形式執行此作業,請使用 CopyFileTransacted 函式 。
語法
BOOL CopyFileA(
[in] LPCSTR lpExistingFileName,
[in] LPCSTR lpNewFileName,
[in] BOOL bFailIfExists
);
參數
[in] lpExistingFileName
現有檔案的名稱。
根據預設,名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元,請在路徑前面加上 “\\?\”。 如需詳細資訊,請參閱命名檔案、路徑與命名空間。
提示
從 Windows 10 版本 1607 開始,您可以選擇移除MAX_PATH限制,而不需在前面加上 “\\?\”。 如需詳細資訊,請參閱 命名檔案、路徑和命名空間 的一節。
如果 lpExistingFileName 不存在, CopyFile 會失敗,而且 GetLastError 會傳回 ERROR_FILE_NOT_FOUND。
[in] lpNewFileName
新檔案的名稱。
根據預設,名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元,請在路徑前面加上 “\\?\”。 如需詳細資訊,請參閱命名檔案、路徑與命名空間。
提示
從 Windows 10 版本 1607 開始,您可以選擇移除MAX_PATH限制,而不需在前面加上 “\\?\”。 如需詳細資訊,請參閱 命名檔案、路徑和命名空間 的一節。
[in] bFailIfExists
如果此參數為 TRUE ,且 lpNewFileName 指定的新檔案已經存在,則函式會失敗。 如果此參數為 FALSE 且新檔案已經存在,則函式會覆寫現有的檔案並成功。
傳回值
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
將現有檔案的安全性資源屬性 (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_READONLY 檔案屬性,透過呼叫 CopyFile 所建立的複本也會有 FILE_ATTRIBUTE_READONLY 檔案屬性。 如需詳細資訊,請參閱 擷取和變更檔案屬性。
如果目的地檔案已經存在,且已設定FILE_ATTRIBUTE_HIDDEN或FILE_ATTRIBUTE_READONLY屬性,此函式會失敗並ERROR_ACCESS_DENIED。
當 CopyFile 用來複製加密的檔案時,它會嘗試使用來源檔案加密中使用的金鑰來加密目的地檔案。 如果無法這麼做,此函式會嘗試使用預設密鑰來加密目的地檔案。 如果這兩種方法都無法完成, CopyFile 會失敗,並 出現ERROR_ENCRYPTION_FAILED 錯誤碼。
符號連結行為: 如果來源檔案是符號連結,則複製的實際檔案是符號鏈接的目標。
如果目的地檔案已經存在,而且是符號連結,則來源檔案會覆寫符號鏈接的目標。
在 Windows 8 和 Windows Server 2012 中,下列技術支援此函式。
技術 | 支援 |
---|---|
伺服器消息塊 (SMB) 3.0 通訊協定 | Yes |
SMB 3.0 透明故障轉移 (TFO) | Yes |
具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
叢集共用磁碟區文件系統 (CsvFS) | Yes |
彈性檔案系統 (ReFS) | 是 |
範例
如需範例,請參閱 擷取和變更檔案屬性。
注意
winbase.h 標頭會將 CopyFile 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | winbase.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |