Fungsi CopyFileTransactedA (winbase.h)

Artikel
06/02/2023

[Microsoft sangat menyarankan pengembang menggunakan cara alternatif untuk mencapai kebutuhan aplikasi Anda. Banyak skenario yang dikembangkan TxF dapat dicapai melalui teknik yang lebih sederhana dan lebih tersedia. Selain itu, TxF mungkin tidak tersedia di versi Microsoft Windows yang akan datang. Untuk informasi lebih lanjut, dan alternatif TxF, silakan lihat Alternatif untuk menggunakan Transactional NTFS.]

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

Sintaks

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

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

File harus berada di komputer lokal; jika tidak, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[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_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.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Operasi salin gagal segera jika file target sudah ada.
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.

[in] hTransaction

Handel ke transaksi. Handel ini dikembalikan oleh fungsi CreateTransaction .

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, CopyFileTransacted 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, CopyFileTransacted akan mengembalikan nol dan GetLastError akan mengembalikan ERROR_REQUEST_ABORTED. Dalam hal ini, file tujuan yang disalin sebagian dibiarkan utuh.

Jika Anda mencoba memanggil fungsi ini dengan handel ke transaksi yang telah digulung balik, CopyFileTransacted akan mengembalikan ERROR_TRANSACTION_NOT_ACTIVE atau ERROR_INVALID_TRANSACTION.

Keterangan

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

Windows 7, Windows Server 2008 R2, Windows Server 2008, dan Windows Vista: Atribut sumber daya keamanan (ATTRIBUTE_SECURITY_INFORMATION) 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 .

File terenkripsi tidak didukung oleh TxF.

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.

Pelacakan tautan tidak didukung oleh TxF.

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

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

Perhatikan bahwa SMB 3.0 tidak mendukung TxF.

Catatan

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


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll