Fungsi CopyFileA (winbase.h)

Artikel
11/20/2024

Menyalin file yang sudah 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.

Sintaksis

BOOL CopyFileA(
  [in] LPCSTR lpExistingFileName,
  [in] LPCSTR lpNewFileName,
  [in] BOOL   bFailIfExists
);

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.

Ujung

Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa prepending "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" 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.

Ujung

[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, panggil GetLastError.

Komentar

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, file tersebut 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 ada metode ini yang 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
Failover Transparan (TFO) SMB 3.0	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.

Nota

Header winbase.h mendefinisikan CopyFile 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

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

Lihat juga

CopyFileEx

CopyFileTransacted

CreateFile

Konstanta Atribut File

File Management Functions

MoveFile

Tautan Simbolis

Bagikan melalui