Fungsi SHFileOperationA (shellapi.h)
Menyalin, memindahkan, mengganti nama, atau menghapus objek sistem file. Fungsi ini telah digantikan di Windows Vista oleh IFileOperation.
Sintaks
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
Parameter
[in, out] lpFileOp
Jenis: LPSHFILEOPSTRUCT
Penunjuk ke struktur SHFILEOPSTRUCT yang berisi informasi yang diperlukan fungsi ini untuk melakukan operasi yang ditentukan. Parameter ini harus berisi nilai valid yang bukan NULL. Anda bertanggung jawab untuk memvalidasi nilai. Jika Anda tidak memvalidasinya, Anda akan mengalami hasil yang tidak terduga.
Nilai kembali
Jenis: int
Mengembalikan nol jika berhasil; jika tidak nol. Aplikasi biasanya hanya harus memeriksa nol atau nonzero.
Adalah praktik yang baik untuk memeriksa nilai anggota fAnyOperationsAborted dari SHFILEOPSTRUCT. SHFileOperation dapat mengembalikan 0 agar berhasil jika pengguna membatalkan operasi. Jika Anda tidak memeriksa fAnyOperationsAborted serta nilai pengembalian, Anda tidak dapat mengetahui bahwa fungsi menyelesaikan tugas penuh yang Anda minta dan Anda mungkin melanjutkan dengan asumsi yang salah.
Jangan gunakan GetLastError dengan nilai pengembalian fungsi ini.
Untuk memeriksa nilai bukan nol untuk tujuan pemecahan masalah, nilai tersebut sebagian besar memetakan ke nilai yang ditentukan dalam Winerror.h. Namun, beberapa nilai pengembalian yang mungkin didasarkan pada kode kesalahan pra-Win32, yang dalam beberapa kasus tumpang tindih dengan nilai Winerror.h nanti tanpa mencocokkan maknanya. Nilai-nilai tertentu tersebut dirinci di sini, dan untuk nilai-nilai spesifik ini hanya makna-makna ini yang harus diterima melalui kode Winerror.h. Namun, nilai-nilai ini disediakan dengan peringatan ini:
- Ini adalah kode kesalahan pra-Win32 dan tidak lagi didukung atau didefinisikan dalam file header publik apa pun. Untuk menggunakannya, Anda harus menentukannya sendiri atau membandingkannya dengan nilai numerik.
- Kode kesalahan ini dapat berubah dan secara historis melakukannya.
- Nilai-nilai ini hanya disediakan sebagai bantuan dalam penelusuran kesalahan. Mereka tidak boleh dianggap sebagai definitif.
| Kode Kesalahan | Nilai | Makna |
|---|---|---|
| DE_SAMEFILE | 0x71 | File sumber dan tujuan adalah file yang sama. |
| DE_MANYSRC1DEST | 0x72 | Beberapa jalur file ditentukan dalam buffer sumber, tetapi hanya satu jalur file tujuan. |
| DE_DIFFDIR | 0x73 | Operasi ganti nama ditentukan tetapi jalur tujuan adalah direktori yang berbeda. Gunakan operasi pemindahan sebagai gantinya. |
| DE_ROOTDIR | 0x74 | Sumber adalah direktori akar, yang tidak dapat dipindahkan atau diganti namanya. |
| DE_OPCANCELLED | 0x75 | Operasi dibatalkan oleh pengguna, atau dibatalkan secara diam-diam jika bendera yang sesuai diberikan ke SHFileOperation. |
| DE_DESTSUBTREE | 0x76 | Tujuannya adalah subtree sumber. |
| DE_ACCESSDENIEDSRC | 0x78 | Pengaturan keamanan menolak akses ke sumber. |
| DE_PATHTOODEEP | 0x79 | Jalur sumber atau tujuan terlampaui atau akan melebihi MAX_PATH. |
| DE_MANYDEST | 0x7A | Operasi ini melibatkan beberapa jalur tujuan, yang dapat gagal dalam kasus operasi pemindahan. |
| DE_INVALIDFILES | 0x7C | Jalur di sumber atau tujuan atau keduanya tidak valid. |
| DE_DESTSAMETREE | 0x7D | Sumber dan tujuan memiliki folder induk yang sama. |
| DE_FLDDESTISFILE | 0x7E | Jalur tujuan adalah file yang sudah ada. |
| DE_FILEDESTISFLD | 0x80 | Jalur tujuan adalah folder yang sudah ada. |
| DE_FILENAMETOOLONG | 0x81 | Nama file melebihi MAX_PATH. |
| DE_DEST_IS_CDROM | 0x82 | Tujuannya adalah CD-ROM baca-saja, mungkin tidak diformat. |
| DE_DEST_IS_DVD | 0x83 | Tujuannya adalah DVD baca-saja, mungkin tidak diformat. |
| DE_DEST_IS_CDRECORD | 0x84 | Tujuannya adalah CD-ROM bisa-tulis, mungkin tidak diformat. |
| DE_FILE_TOO_LARGE | 0x85 | File yang terlibat dalam operasi terlalu besar untuk media tujuan atau sistem file. |
| DE_SRC_IS_CDROM | 0x86 | Sumbernya adalah CD-ROM baca-saja, mungkin tidak diformat. |
| DE_SRC_IS_DVD | 0x87 | Sumbernya adalah DVD baca-saja, mungkin tidak diformat. |
| DE_SRC_IS_CDRECORD | 0x88 | Sumbernya adalah CD-ROM bisa-tulis, mungkin tidak diformat. |
| DE_ERROR_MAX | 0xB7 | MAX_PATH terlampaui selama operasi. |
| 0x402 | Terjadi kesalahan yang tidak diketahui. Ini biasanya karena jalur yang tidak valid di sumber atau tujuan. Kesalahan ini tidak terjadi pada Windows Vista dan yang lebih baru. | |
| ERRORONDEST | 0x10000 | Terjadi kesalahan yang tidak ditentukan pada tujuan. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | Tujuan adalah direktori akar dan tidak dapat diganti namanya. |
Keterangan
Anda harus menggunakan nama jalur yang sepenuhnya memenuhi syarat dengan fungsi ini. Menggunakannya dengan nama jalur relatif tidak aman untuk utas.
Dengan dua pengecualian, Anda tidak dapat menggunakan SHFileOperation untuk memindahkan folder khusus dari drive lokal ke komputer jarak jauh dengan menentukan jalur jaringan. Pengecualiannya adalah folder Dokumen Saya (CSIDL_PERSONAL, CSIDL_DOCUMENTS) dan Gambar Saya (CSIDL_MYPICTURES).
Ketika digunakan untuk menghapus file, SHFileOperation menghapus file secara permanen kecuali Anda mengatur bendera FOF_ALLOWUNDO di anggota fFlags struktur SHFILEOPSTRUCT yang ditunjukkan oleh lpFileOp. Pengaturan bendera tersebut mengirimkan file ke Keranjang Sampah. Jika Anda hanya ingin menghapus file dan menjamin bahwa file tersebut tidak ditempatkan di Keranjang Sampah, gunakan DeleteFile.
Jika handler panggilan balik salinan diekspos dan terdaftar, SHFileOperation memanggilnya kecuali Anda mengatur bendera seperti FOF_NOCONFIRMATION di anggota fFlags struktur yang diarahkan oleh lpFileOp. Lihat ICopyHook::CopyCallback untuk detail tentang menerapkan penanganan panggilan balik salin.
Penghapusan file bersifat rekursif kecuali Anda mengatur bendera FOF_NORECURSION di lpFileOp.
Menyambungkan File
Dengan Windows 2000 atau yang lebih baru, dimungkinkan untuk menyambungkan file HTML dengan folder yang berisi file terkait seperti gambar Graphics Interchange Format (GIF) atau lembar gaya. Jika koneksi file diaktifkan, saat Anda memindahkan atau menyalin file HTML, folder yang tersambung dan semua filenya juga dipindahkan atau disalin. Sebaliknya, jika Anda memindahkan folder dengan file terkait, file HTML juga dipindahkan.File HTML harus memiliki ekstensi .htm atau .html. Anda membuat koneksi ke file terkait dengan menempatkan folder yang berisinya ke dalam folder yang sama dengan file HTML. Nama folder yang berisi file yang terhubung harus sama dengan nama file HTML diikuti dengan "_files" atau ".files" (ini peka huruf besar/kecil; misalnya, ". File" tidak berfungsi). Contoh diberikan di sini.
- Buat file bernama Test.htm di direktori C:\Files (C:\Files\Test.htm).
- Buat folder baru bernama Test.files di direktori C:\Files (C:\Files\Test.files).
- Isi folder dengan beberapa file. File apa pun yang ditempatkan di folder ini tersambung ke Test.htm.
- Pindahkan atau salin file Test.htm ke direktori C:\Files2.
- Perhatikan bahwa direktori Test.files sekarang ditemukan di direktori C:\Files2 juga.
Koneksi file diaktifkan secara default. Ini dapat dinonaktifkan dengan menambahkan entri REG_DWORD , NoFileFolderConnection, seperti yang ditunjukkan di sini:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
Mengatur NoFileFolderConnection ke 1 menonaktifkan koneksi file. Jika nilai diatur ke nol atau hilang, koneksi file diaktifkan.
Untuk memindahkan hanya file yang ditentukan dan tidak ada file yang terhubung, atur bendera FOF_NO_CONNECTED_ELEMENTS di anggota fFlags struktur yang diarahkan oleh lpFileOp.
Perhatikan bahwa penggunaan folder dengan nama seperti "MyFile_files" untuk menentukan koneksi mungkin tidak valid untuk versi Windows yang dilokalkan. Istilah "file" mungkin perlu digantikan oleh kata yang setara dalam bahasa lokal.
Catatan
Header shellapi.h mendefinisikan SHFileOperation 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
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | shellapi.h |
| Pustaka | Shell32.lib |
| DLL | Shell32.dll (versi 4.0 atau yang lebih baru) |
| Set API | ext-ms-win-shell-shell32-l1-2-1 (diperkenalkan dalam Windows 10, versi 10.0.10240) |
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk