Fungsi CopyFile2 (winbase.h)

Artikel
08/27/2023

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

Sintaks

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

Parameter

[in] pwszExistingFileName

Nama file yang ada.

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

Tips Mulai dari Windows 10, versi 1607, Anda dapat memilih untuk menghapus batasan karakter MAX_PATH tanpa menambahkan "\\?\". Lihat bagian "Batasan Jalur Maksimum" di Penamaan File, Jalur, dan Namespace untuk detailnya.

Jika lpExistingFileName tidak ada, fungsi CopyFile2 gagal mengembalikan HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).

[in] pwszNewFileName

Nama file baru.

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

[in, optional] pExtendedParameters

Alamat opsional struktur COPYFILE2_EXTENDED_PARAMETERS .

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan akan mengembalikan TRUE saat diteruskan ke makro BERHASIL .

Menampilkan kode	Deskripsi
S_OK	Operasi salin berhasil diselesaikan.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)	Operasi salin dijeda oleh pengembalian COPYFILE2_PROGRESS_PAUSE dari fungsi panggilan balik CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)	Operasi salin dijeda oleh pengembalian COPYFILE2_PROGRESS_CANCEL atau COPYFILE2_PROGRESS_STOP dari fungsi panggilan balik CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)	Anggota dwCopyFlags dari struktur COPYFILE2_EXTENDED_PARAMETERS melewati parameter pExtendedParameters berisi bendera COPY_FILE_FAIL_IF_EXISTS dan nama yang bertentangan ada.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)	Anggota dwCopyFlags dari struktur COPYFILE2_EXTENDED_PARAMETERS melewati parameter pExtendedParameters berisi bendera COPY_FILE_FAIL_IF_EXISTS dan nama yang bertentangan ada.

Keterangan

Fungsi ini mempertahankan atribut yang diperluas, penyimpanan terstruktur OLE, aliran data alternatif sistem file NTFS, dan atribut file. Atribut keamanan untuk file yang ada tidak disalin ke file baru. Untuk menyalin atribut keamanan, gunakan fungsi SHFileOperation .

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

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan makro _WIN32_WINNT sebagai _WIN32_WINNT_WIN8 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.

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 Berbagi File Peluasan Skala (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Dimulai dengan Windows 10, versi 1903 dan Windows Server 2022, nilai baru, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, didukung untuk bidang dwCopyFlags dari struktur COPYFILE2_EXTENDED_PARAMETERS yang diteruskan dalam argumen pExtendedParameters ke fungsi ini. Nilai baru ini meminta agar saluran transfer yang mendasar memadatkan 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. 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.

Persyaratan


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

Lihat juga

COPYFILE2_EXTENDED_PARAMETERS

Fungsi Manajemen File

Bagikan melalui