Struktur SHFILEOPSTRUCTA (shellapi.h)
Berisi informasi yang digunakan fungsi
Sintaksis
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
Anggota
hwnd
Jenis: HWND
Handel jendela ke kotak dialog untuk menampilkan informasi tentang status operasi file.
wFunc
Jenis: UINT
Nilai yang menunjukkan operasi mana yang akan dilakukan. Salah satu nilai berikut:
FO_COPY
Salin file yang ditentukan dalam anggota
FO_DELETE
Hapus file yang ditentukan dalam pDari.
FO_MOVE
Pindahkan file yang ditentukan dalam pDari ke lokasi yang ditentukan dalam pTo.
FO_RENAME
Ganti nama file yang ditentukan dalam pDari. Anda tidak dapat menggunakan bendera ini untuk mengganti nama beberapa file dengan satu panggilan fungsi. Gunakan FO_MOVE sebagai gantinya.
pFrom
Jenis: PCZZTSTR
Karakter kartubebas MS-DOS standar, seperti "*", diizinkan hanya dalam posisi nama file. Menggunakan karakter kartubebas di tempat lain dalam string akan menyebabkan hasil yang tidak dapat diprediksi.
Meskipun anggota ini dinyatakan sebagai string tunggal yang dihentikan null, itu sebenarnya adalah buffer yang dapat menampung beberapa nama file yang dibatasi null. Setiap nama file dihentikan oleh satu karakter NULL. Nama file terakhir dihentikan dengan karakter null ganda ("\0\0") untuk menunjukkan akhir buffer.
pTo
Jenis: PCZZTSTR
Seperti
- Karakter kartubebas tidak didukung.
- Operasi Salin dan Pindahkan dapat menentukan direktori tujuan yang tidak ada. Dalam kasus tersebut, sistem mencoba membuatnya dan biasanya menampilkan kotak dialog untuk bertanya kepada pengguna apakah mereka ingin membuat direktori baru. Untuk menekan kotak dialog ini dan membuat direktori dibuat secara diam-diam, atur bendera FOF_NOCONFIRMMKDIR di fFlags.
- Untuk operasi Salin dan Pindahkan, buffer dapat berisi beberapa nama file tujuan jika anggota fFlags menentukan FOF_MULTIDESTFILES.
- Kemas beberapa nama ke dalam string pTo
dengan cara yang sama seperti untuk pFrom . - Gunakan jalur yang sepenuhnya memenuhi syarat. Menggunakan jalur relatif tidak dilarang, tetapi dapat memiliki hasil yang tidak dapat diprediksi.
fFlags
Jenis: FILEOP_FLAGS
Bendera yang mengontrol operasi file. Anggota ini dapat mengambil kombinasi bendera berikut.
FOF_ALLOWUNDO
Pertahankan batalkan informasi, jika memungkinkan.
Sebelum Windows Vista, operasi hanya dapat dibatalkan dari proses yang sama yang melakukan operasi asli.
Di Windows Vista dan sistem yang lebih baru, cakupan urungkan adalah sesi pengguna. Setiap proses yang berjalan dalam sesi pengguna dapat membatalkan operasi lain. Status batalkan diadakan dalam proses Explorer.exe, dan selama proses tersebut berjalan, itu dapat mengoordinasikan fungsi batalkan.
Jika parameter file sumber tidak berisi jalur dan nama file yang sepenuhnya memenuhi syarat, bendera ini diabaikan.
FOF_CONFIRMMOUSE
Tidak digunakan.
FOF_FILESONLY
Lakukan operasi hanya pada file (bukan pada folder) jika nama file kartubebas (.) ditentukan.
FOF_MULTIDESTFILES
Anggota pTo
FOF_NOCONFIRMATION
Tanggapi dengan Ya untuk Semua untuk kotak dialog apa pun yang ditampilkan.
FOF_NOCONFIRMMKDIR
Jangan minta pengguna untuk mengonfirmasi pembuatan direktori baru jika operasi mengharuskan operasi dibuat.
FOF_NO_CONNECTED_ELEMENTS
Versi 5.0. Jangan pindahkan file yang tersambung sebagai grup. Hanya pindahkan file yang ditentukan.
FOF_NOCOPYSECURITYATTRIBS
Versi 4.71. Jangan salin atribut keamanan file. File tujuan menerima atribut keamanan folder barunya.
FOF_NOERRORUI
Jangan tampilkan dialog kepada pengguna jika terjadi kesalahan.
FOF_NORECURSEREPARSE
Tidak digunakan.
FOF_NORECURSION
Hanya lakukan operasi di direktori lokal. Jangan beroperasi secara rekursif ke dalam subdirektori, yang merupakan perilaku default.
FOF_NO_UI
Windows Vista. Lakukan operasi secara diam-diam, tanpa menyajikan UI kepada pengguna. Ini setara dengan FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Berikan file yang sedang dioperasikan pada nama baru dalam operasi pindah, salin, atau ganti nama jika file dengan nama target sudah ada di tujuan.
FOF_SILENT
Jangan tampilkan kotak dialog kemajuan.
FOF_SIMPLEPROGRESS
Tampilkan kotak dialog kemajuan tetapi jangan perlihatkan nama file individual saat dioperasikan.
FOF_WANTMAPPINGHANDLE
Jika FOF_RENAMEONCOLLISION ditentukan dan file apa pun diganti namanya, tetapkan objek pemetaan nama yang berisi nama lama dan baru mereka ke hNameMappings anggota. Objek ini harus dibebaskan menggunakan SHFreeNameMappings ketika tidak lagi diperlukan.
FOF_WANTNUKEWARNING
Versi 5.0. Kirim peringatan jika file dihancurkan secara permanen selama operasi penghapusan daripada didaur ulang. Bendera ini sebagian mengambil alih FOF_NOCONFIRMATION.
fAnyOperationsAborted
Jenis: BOOL
Ketika fungsi kembali, anggota ini berisi TRUE jika ada operasi file yang dibatalkan sebelum selesai; jika tidak, FALSE. Operasi dapat dibatalkan secara manual oleh pengguna melalui UI atau dapat dibatalkan secara diam-diam oleh sistem jika bendera FOF_NOERRORUI atau FOF_NOCONFIRMATION ditetapkan.
hNameMappings
Jenis:
Ketika fungsi kembali, anggota ini berisi handel ke objek pemetaan nama yang berisi nama lama dan baru dari file yang diganti namanya. Anggota ini hanya digunakan jika anggota fFlags menyertakan bendera FOF_WANTMAPPINGHANDLE. Lihat Keterangan untuk detail selengkapnya.
lpszProgressTitle
Jenis: PCTSTR
Penunjuk ke judul kotak dialog kemajuan. Ini adalah string null-terminated. Anggota ini hanya digunakan jika fFlags menyertakan bendera FOF_SIMPLEPROGRESS.
Komentar
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Untuk memperhitungkan dua karakter null yang mengakhiri, pastikan untuk membuat buffer yang cukup besar untuk menahan MAX_PATH (yang biasanya mencakup karakter null penghentian tunggal) ditambah 1.
Tidak dapat dilebih-lebihkan bahwa jalur Anda harus selalu menjadi jalur penuh. Jika anggota
Jika Anda tidak memberikan jalur lengkap, fakta berikut menjadi berkaitan:
- Kurangnya jalur sebelum nama file tidak menunjukkan SHFileOperation bahwa file ini berada di akar direktori saat ini.
- Variabel lingkungan PATH tidak digunakan oleh
SHFileOperation untuk menentukan jalur yang valid. - SHFileOperation tidak dapat diandalkan untuk menggunakan direktori yang merupakan direktori saat ini ketika mulai dijalankan. Direktori yang dilihat sebagai direktori saat ini bersifat seluruh proses, dan dapat diubah dari utas lain saat operasi dijalankan. Jika itu terjadi, hasil SHFileOperation tidak dapat diprediksi.
Jika pFrom diatur ke nama file tanpa jalur lengkap, menghapus file dengan FO_DELETE tidak memindahkannya ke Keranjang Sampah, meskipun bendera FOF_ALLOWUNDO diatur. Anda harus menyediakan jalur lengkap untuk menghapus file ke Keranjang Sampah.
SHFileOperation gagal pada jalur apa pun yang diawali dengan "\?".
Ada dua versi struktur ini, versi ANSI (SHFILEOPSTRUCTA) dan versi Unicode (SHFILEOPSTRUCTW). Versi Unicode identik dengan versi ANSI, kecuali bahwa string karakter lebar (LPCWSTR) digunakan sebagai pengganti string karakter ANSI (LPCSTR). Pada Windows 98 dan yang lebih lama, hanya versi ANSI yang didukung. Pada Microsoft Windows NT 4.0 dan yang lebih baru, versi ANSI dan Unicode dari struktur ini didukung. SHFILEOPSTRUCTW dan SHFILEOPTSTRUCTA tidak boleh digunakan secara langsung; struktur yang sesuai didefinisikan ulang sebagai SHFILEOPSTRUCT oleh prakompilasi tergantung pada apakah aplikasi dikompilasi untuk ANSI atau Unicode.
SHNAMEMAPPING memiliki versi ANSI dan Unicode yang serupa. Untuk aplikasi ANSI,
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Perlakukan
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
Nilai UINT
Nota
Header shellapi.h mendefinisikan SHFILEOPSTRUCT 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] |
Header |
shellapi.h |
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
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:Kirim dan lihat umpan balik untuk