Fungsi CopyFileTransactedA (winbase.h)

[Microsoft sangat merekomendasikan pengembang menggunakan sarana 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 menggunakanNTFS Transaksi.]

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

Sintaksis

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 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, 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.

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.

[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.

Nilai Arti
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 diacu oleh tautan simbolis sumber.
COPY_FILE_FAIL_IF_EXISTS
0x00000001
 Operasi salin segera gagal 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 penyalinan secara signifikan karena file baru dapat dihapus beberapa kali selama operasi penyalinan.

[in] hTransaction

Handel ke transaksi. Handel ini dikembalikan oleh fungsi CreateTransaction.

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, 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 kembali 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.

Komentar

Fungsi ini mempertahankan atribut yang diperluas, penyimpanan terstruktur OLE, sistem file NTFS aliran data alternatif, 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
Failover Transparan (TFO) SMB 3.0 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.

Nota

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

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

Lihat juga

CopyProgressRoutine

CreateFileTransacted

Konstanta Atribut File

File Management Functions

MoveFileTransacted

Tautan Simbolis

Transaksi NTFS

  • Last updated on