Fungsi CopyFile (winbase.h)

Artikel
06/02/2023

Menyalin file yang ada ke file baru.

Fungsi CopyFileEx menyediakan dua kemampuan tambahan. CopyFileEx dapat memanggil fungsi panggilan balik tertentu setiap kali sebagian operasi salin selesai, dan CopyFileEx dapat dibatalkan selama operasi salin.

Untuk melakukan operasi ini sebagai operasi yang ditransaksikan, gunakan fungsi CopyFileTransacted .

Sintaks

BOOL CopyFile(
  [in] LPCTSTR lpExistingFileName,
  [in] LPCTSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

Parameter

[in] lpExistingFileName

Nama file yang ada.

Secara default, nama terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Tip

Dimulai dengan Windows 10, Versi 1607, Anda dapat ikut serta untuk menghapus batasan MAX_PATH tanpa menambahkan awalan "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" dari Penamaan File, Jalur, dan Namespace untuk detailnya.

Jika lpExistingFileName tidak ada, CopyFile gagal, dan GetLastError mengembalikan ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nama file baru.

Tip

[in] bFailIfExists

Jika parameter ini TRUE dan file baru yang ditentukan oleh lpNewFileName sudah ada, fungsi gagal. Jika parameter ini FALSE dan file baru sudah ada, fungsi akan menimpa file yang ada dan berhasil.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Properti sumber daya keamanan (ATTRIBUTE_SECURITY_INFORMATION) untuk file yang ada disalin ke file baru.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003, dan Windows XP: Properti sumber daya keamanan untuk file yang ada tidak disalin ke file baru hingga Windows 8 dan Windows Server 2012.

Atribut file untuk file yang ada disalin ke file baru. Misalnya, jika file yang ada memiliki atribut file FILE_ATTRIBUTE_READONLY , salinan yang dibuat melalui panggilan ke CopyFile juga akan memiliki atribut file FILE_ATTRIBUTE_READONLY . Untuk informasi selengkapnya, lihat Mengambil dan Mengubah Atribut File.

Fungsi ini gagal dengan ERROR_ACCESS_DENIED jika file tujuan sudah ada dan memiliki set atribut FILE_ATTRIBUTE_HIDDEN atau FILE_ATTRIBUTE_READONLY .

Ketika CopyFile digunakan untuk menyalin file terenkripsi, copyFile mencoba mengenkripsi file tujuan dengan kunci yang digunakan dalam enkripsi file sumber. Jika ini tidak dapat dilakukan, fungsi ini mencoba mengenkripsi file tujuan dengan kunci default. Jika tidak satu pun dari metode ini dapat dilakukan, CopyFile gagal dengan kode kesalahan ERROR_ENCRYPTION_FAILED .

Perilaku tautan simbolis—Jika file sumber adalah tautan simbolis, file aktual yang disalin adalah target tautan simbolis.

Jika file tujuan sudah ada dan merupakan tautan simbolis, target tautan simbolis ditimpa oleh file sumber.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Contoh

Misalnya, lihat Mengambil dan Mengubah Atribut File.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll