Fungsi CopyFileExA (winbase.h)

Artikel
03/03/2024

Menyalin file yang ada ke file baru, memberi tahu aplikasi kemajuannya melalui fungsi panggilan balik.

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

Sintaks

BOOL CopyFileExA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags
);

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, fungsi CopyFileEx gagal, dan fungsi GetLastError mengembalikan ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nama file baru.

Tip

[in, optional] lpProgressRoutine

Alamat fungsi panggilan balik jenis LPPROGRESS_ROUTINE yang dipanggil setiap kali bagian lain dari file telah disalin. Parameter ini bisa NULL. Untuk informasi selengkapnya tentang fungsi panggilan balik kemajuan, lihat fungsi CopyProgressRoutine .

[in, optional] lpData

Argumen yang akan diteruskan ke fungsi panggilan balik. Parameter ini bisa NULL.

[in, optional] pbCancel

Jika bendera ini diatur ke TRUE selama operasi salin, operasi dibatalkan. Jika tidak, operasi salin akan terus selesai.

[in] dwCopyFlags

Bendera yang menentukan bagaimana file akan disalin. Parameter ini bisa menjadi kombinasi dari nilai berikut.

Nilai	Makna
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	Upaya untuk menyalin file terenkripsi akan berhasil meskipun salinan tujuan tidak dapat dienkripsi.
COPY_FILE_COPY_SYMLINK 0x00000800	Jika file sumber adalah tautan simbolis, file tujuan juga merupakan tautan simbolis yang menunjuk ke file yang sama dengan yang ditujukan oleh tautan simbolis sumber. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Operasi salin gagal segera jika file target sudah ada.
COPY_FILE_NO_BUFFERING 0x00001000	Operasi salin dilakukan menggunakan I/O yang tidak dibuffer, melewati sumber daya cache I/O sistem. Direkomendasikan untuk transfer file yang sangat besar. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	File disalin dan file asli dibuka untuk akses tulis.
COPY_FILE_RESTARTABLE 0x00000002	Kemajuan salinan dilacak dalam file target jika salinan gagal. Salinan yang gagal dapat dimulai ulang di lain waktu dengan menentukan nilai yang sama untuk lpExistingFileName dan lpNewFileName seperti yang digunakan dalam panggilan yang gagal. Ini dapat memperlambat operasi salin secara signifikan karena file baru dapat dibersihkan beberapa kali selama operasi salin.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	Minta saluran transfer yang mendasar mengompres data selama operasi salin. Permintaan mungkin tidak didukung untuk semua media, dalam hal ini diabaikan. Atribut dan parameter kompresi (kompleksitas komputasi, penggunaan memori) tidak dapat dikonfigurasi melalui API ini, dan dapat berubah di antara rilis OS yang berbeda. Bendera ini diperkenalkan di Windows 10, versi 1903 dan Windows Server 2022. Pada Windows 10, bendera didukung untuk file yang berada di berbagi SMB, di mana versi protokol SMB yang dinegosiasikan adalah SMB v3.1.1 atau lebih besar.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Jika lpProgressRoutine mengembalikan PROGRESS_CANCEL karena pengguna membatalkan operasi, CopyFileEx akan mengembalikan nol dan GetLastError akan mengembalikan ERROR_REQUEST_ABORTED. Dalam hal ini, file tujuan yang disalin sebagian dihapus.

Jika lpProgressRoutine mengembalikan PROGRESS_STOP karena pengguna menghentikan operasi, CopyFileEx akan mengembalikan nol dan GetLastError akan mengembalikan ERROR_REQUEST_ABORTED. Dalam hal ini, file tujuan yang disalin sebagian dibiarkan utuh.

Keterangan

Fungsi ini mempertahankan atribut yang diperluas, penyimpanan terstruktur OLE, aliran data alternatif sistem file NTFS, atribut sumber daya keamanan, dan atribut file.

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

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.

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

Ketika file terenkripsi disalin menggunakan CopyFileEx, fungsi 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 kedua metode ini tidak dapat dilakukan, CopyFileEx gagal dengan kode kesalahan ERROR_ENCRYPTION_FAILED . Jika Anda ingin CopyFileEx menyelesaikan operasi salin meskipun file tujuan tidak dapat dienkripsi, sertakan COPY_FILE_ALLOW_DECRYPTED_DESTINATION sebagai nilai parameter dwCopyFlags dalam panggilan Anda ke CopyFileEx.

Jika COPY_FILE_COPY_SYMLINK ditentukan, aturan berikut berlaku:

Jika file sumber adalah tautan simbolis, tautan simbolis disalin, bukan file target.
Jika file sumber bukan tautan simbolis, tidak ada perubahan perilaku.
Jika file tujuan adalah tautan simbolis yang ada, tautan simbolis ditimpa, bukan file target.
Jika COPY_FILE_FAIL_IF_EXISTS juga ditentukan, dan file tujuan adalah tautan simbolis yang ada, operasi gagal dalam semua kasus.

Jika COPY_FILE_COPY_SYMLINK tidak ditentukan, aturan berikut berlaku:

Jika COPY_FILE_FAIL_IF_EXISTS juga ditentukan, dan file tujuan adalah tautan simbolis yang ada, operasi hanya gagal jika target tautan simbolis ada.
Jika COPY_FILE_FAIL_IF_EXISTS tidak ditentukan, tidak ada perubahan perilaku.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003, dan Windows XP: Jika Anda menulis aplikasi yang mengoptimalkan operasi penyalinan file di seluruh LAN, pertimbangkan untuk menggunakan fungsi TransmitFile dari Windows Sockets (Winsock). TransmitFile mendukung transfer jaringan berkinerja tinggi dan menyediakan antarmuka sederhana untuk mengirim konten file ke komputer jarak jauh. Untuk menggunakan TransmitFile, Anda harus menulis aplikasi klien Winsock yang mengirim file dari komputer sumber serta aplikasi server Winsock yang menggunakan fungsi Winsock lainnya untuk menerima file di komputer jarak jauh.

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

Catatan

Header winbase.h mendefinisikan CopyFileEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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