Fungsi SHFileOperationW (shellapi.h)

Artikel
2024-11-20

Menyalin, memindahkan, mengganti nama, atau menghapus objek sistem file. Fungsi ini telah digantikan di Windows Vista oleh IFileOperation.

Sintaksis

int SHFileOperationW(
  [in, out] LPSHFILEOPSTRUCTW 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 tidak NULL. Anda bertanggung jawab untuk memvalidasi nilai. Jika Anda tidak memvalidasinya, Anda akan mengalami hasil yang tidak terduga.

Mengembalikan nilai

Jenis: int

Mengembalikan nol jika berhasil; jika tidak, bukan nol. Aplikasi biasanya hanya harus memeriksa nol atau nonzero.

Adalah praktik yang baik untuk memeriksa nilai fAnyOperationsAborted anggota SHFILEOPSTRUCT. SHFileOperation dapat mengembalikan 0 agar berhasil jika pengguna membatalkan operasi. Jika Anda tidak memeriksa fAnyOperationsAborted serta nilai pengembalian, Anda tidak dapat tahu 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 nonzero 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 yang lebih baru tanpa mencocokkan maknanya. Nilai-nilai tertentu dirinci di sini, dan untuk nilai-nilai spesifik ini hanya arti ini 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 ditentukan 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 definitif.

Kode Kesalahan	Nilai	Arti
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.

Komentar

Anda harus menggunakan nama jalur yang sepenuhnya memenuhi syarat dengan fungsi ini. Menggunakannya dengan nama jalur relatif tidak aman 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 Dokumen Saya (CSIDL_PERSONAL, CSIDL_DOCUMENTS) dan folder Gambar Saya (CSIDL_MYPICTURES).

Ketika digunakan untuk menghapus file, SHFileOperation menghapus file secara permanen kecuali Anda mengatur bendera FOF_ALLOWUNDO di fFlags anggota struktur SHFILEOPSTRUCT yang ditujukkan oleh lpFileOp. Pengaturan bendera tersebut mengirim file ke Keranjang Sampah. Jika Anda hanya ingin menghapus file dan menjamin bahwa file tersebut tidak ditempatkan di Keranjang Sampah, gunakan DeleteFile.

Jika handler callback salinan diekspos dan terdaftar, SHFileOperation memanggilnya kecuali Anda mengatur bendera seperti FOF_NOCONFIRMATION di fFlags anggota struktur yang ditunjukkan oleh lpFileOp. Lihat ICopyHook::CopyCallback untuk detail tentang menerapkan handler panggilan balik salinan.

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 atau lembar gaya Graphics Interchange Format (GIF). 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 fFlags anggota 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.

Nota

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

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	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 di Windows 10, versi 10.0.10240)

Bagikan melalui