Fungsi CopyFileExA (winbase.h)

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

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

Sintaksis

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 sudah ada.

Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Penamaan File, Jalur, dan Namespace.

Jika lpExistingFileName tidak ada, fungsi CopyFileEx gagal, dan fungsi GetLastError mengembalikan ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nama file baru.

Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Penamaan File, Jalur, dan Namespace.

[in, optional] lpProgressRoutine

Alamat fungsi panggilan balik jenis LPPROGRESS_ROUTINE yang dipanggil setiap kali bagian lain dari file telah disalin. Parameter ini dapat 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 dapat null.

[in, optional] pbCancel

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

[in] dwCopyFlags

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

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan panggilan informasi kesalahan yang diperluas 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.

Komentar

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 penyalinan 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_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.

Persyaratan

Lihat juga

CopyFile

CopyFileTransacted

CopyProgressRoutine

CreateFile

Konstanta Atribut File

File Management Functions

MoveFile

MoveFileWithProgress

Tautan Simbolis

TransmitFile