Fungsi ReplaceFileA (winbase.h)

Artikel
06/02/2023

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

Sintaks

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, namanya 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 memilih untuk menghapus batasan MAX_PATH tanpa menambahkan sebelumnya "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" di 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 .

Tip

Fungsi ini mencoba membuka file ini dengan hak akses SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE, dan WRITE_DAC sehingga dapat mempertahankan semua atribut dan ACL. Jika gagal, fungsi mencoba membuka file dengan hak akses SYNCHRONIZE, GENERIC_READ, DELETE, dan WRITE_DAC . 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.

Tip

[in] dwReplaceFlags

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

Nilai	Makna
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

Disiapkan untuk penggunaan masa mendatang.

lpReserved

Disiapkan untuk penggunaan masa mendatang.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi 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 digantinya. 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 yang diganti dan diganti 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.

Keterangan

Tips 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" di 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 Penghapusan Selektif, 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 hapus 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 hapus pada saat Anda membuat file, Anda dapat menghapus atau mengganti nama file dengan handel tersebut tetapi tidak dengan yang lain.

Catatan

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


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