Bagikan melalui

Fungsi ReplaceFileA (winbase.h)

  • Artikel

Mengganti satu file dengan file lain, dengan opsi untuk membuat salinan cadangan file asli. File pengganti mengasumsikan nama file yang diganti dan identitasnya.

Sintaksis

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

Parameter

[in] lpReplacedFileName

Nama file yang akan diganti.

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.

File ini dibuka dengan hak akses GENERIC_READ, DELETE, dan SYNCHRONIZE. Mode berbagi FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Pemanggil harus memiliki akses tulis ke file yang akan diganti. Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

[in] lpReplacementFileName

Nama file yang akan menggantikan file lpReplacedFileName.

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.

Fungsi ini mencoba membuka file ini dengan SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, MENGHAPUS, dan WRITE_DAC hak akses sehingga dapat mempertahankan semua atribut dan ACL. Jika ini gagal, fungsi mencoba membuka file dengan SYNCHRONIZE, GENERIC_READ, MENGHAPUS, dan WRITE_DAC hak akses. Tidak ada mode berbagi yang ditentukan.

[in, optional] lpBackupFileName

Nama file yang akan berfungsi sebagai salinan cadangan file lpReplacedFileName. Jika parameter ini NULL, tidak ada file cadangan yang dibuat. Lihat bagian Keterangan untuk detail implementasi pada file cadangan.

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] dwReplaceFlags

Opsi penggantian. Parameter ini bisa berupa satu atau beberapa nilai berikut.

Nilai Arti
REPLACEFILE_WRITE_THROUGH
0x00000001
 Nilai ini tidak didukung.
REPLACEFILE_IGNORE_MERGE_ERRORS
0x00000002
 Mengabaikan kesalahan yang terjadi saat menggabungkan informasi (seperti atribut dan ACL) dari file yang diganti ke file pengganti. Oleh karena itu, jika Anda menentukan bendera ini dan tidak memiliki akses WRITE_DAC, fungsi berhasil tetapi ACL tidak dipertahankan.
REPLACEFILE_IGNORE_ACL_ERRORS
0x00000004
 Mengabaikan kesalahan yang terjadi saat menggabungkan informasi ACL dari file yang diganti ke file pengganti. Oleh karena itu, jika Anda menentukan bendera ini dan tidak memiliki akses WRITE_DAC, fungsi berhasil tetapi ACL tidak dipertahankan. Untuk mengkompilasi aplikasi yang menggunakan nilai ini, tentukan makro _WIN32_WINNT sebagai 0x0600 atau yang lebih baru.

Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.

lpExclude

Dicadangkan untuk digunakan di masa mendatang.

lpReserved

Dicadangkan untuk digunakan di masa mendatang.

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. Berikut ini adalah kemungkinan kode kesalahan untuk fungsi ini.

Mengembalikan kode/nilai Deskripsi
ERROR_UNABLE_TO_MOVE_REPLACEMENT
1176 (0x498)
 File pengganti tidak dapat diganti namanya. Jika lpBackupFileName ditentukan, file pengganti dan pengganti mempertahankan nama file aslinya. Jika tidak, file yang diganti tidak lagi ada dan file pengganti ada dengan nama aslinya.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2
1177 (0x499)
 File pengganti tidak dapat dipindahkan. File pengganti masih ada dengan nama aslinya; namun, ia telah mewarisi aliran file dan atribut dari file yang diganti. File yang akan diganti masih ada dengan nama yang berbeda. Jika lpBackupFileName ditentukan, itu akan menjadi nama file yang diganti.
ERROR_UNABLE_TO_REMOVE_REPLACED
1175 (0x497)
 File yang diganti tidak dapat dihapus. File pengganti dan pengganti mempertahankan nama file aslinya.
 

Jika ada kesalahan lain yang dikembalikan, seperti ERROR_INVALID_PARAMETER, file pengganti dan penggantian akan mempertahankan nama file aslinya. Dalam skenario ini, file cadangan tidak ada dan tidak dijamin bahwa file pengganti akan mewarisi semua atribut dan aliran file yang diganti.

Komentar

Tip Dimulai dengan Windows 10, versi 1607, untuk versi unicode fungsi ini (ReplaceFileW), Anda dapat ikut serta untuk menghapus batasan MAX_PATH. Lihat bagian "Batasan Panjang Jalur Maksimum" Penamaan File, Jalur, dan Namespace untuk detailnya.
 
Fungsi ReplaceFile menggabungkan beberapa langkah dalam satu fungsi. Aplikasi dapat memanggil ReplaceFile alih-alih memanggil fungsi terpisah untuk menyimpan data ke file baru, mengganti nama file asli menggunakan nama sementara, mengganti nama file baru agar memiliki nama yang sama dengan file asli, dan menghapus file asli. Keuntungan lain adalah bahwa ReplaceFile tidak hanya menyalin data file baru, tetapi juga mempertahankan atribut berikut dari file asli:
  • Waktu pembuatan
  • Nama file pendek
  • Pengidentifikasi objek
  • DACL
  • Atribut sumber daya keamanan
  • Enkripsi
  • Kompresi
  • Aliran bernama belum ada dalam file pengganti
Misalnya, jika file pengganti dienkripsi, tetapi file yang diganti tidak dienkripsi, file yang dihasilkan tidak dienkripsi.

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 asli tidak dipertahankan hingga Windows 8 dan Windows Server 2012.

Catatan   

Jika file pengganti dilindungi menggunakan Selective Wipe, maka file yang diganti akan dilindungi oleh id perusahaan dari file pengganti.

 
File yang dihasilkan memiliki ID file yang sama dengan file pengganti.

File cadangan, file yang diganti, dan file pengganti semuanya harus berada pada volume yang sama.

Untuk menghapus atau mengganti nama file, Anda harus memiliki izin penghapusan pada file atau menghapus izin anak di direktori induk. Jika Anda menyiapkan direktori dengan semua akses kecuali menghapus dan menghapus anak dan DACL file baru diwariskan, maka Anda harus dapat membuat file tanpa dapat menghapusnya. Namun, Anda kemudian dapat membuat file, dan Anda akan mendapatkan semua akses yang Anda minta pada handel yang dikembalikan kepada Anda pada saat Anda membuat file. Jika Anda meminta izin penghapusan pada saat Anda membuat file, Anda dapat menghapus atau mengganti nama file dengan handel tersebut tetapi tidak dengan yang lain.

Nota

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

CopyFile

CopyFileEx

File Management Functions

MoveFile

MoveFileEx

MoveFileWithProgress