Bagikan melalui

Struktur SHFILEOPSTRUCTW (shellapi.h)

  • Artikel

Berisi informasi yang digunakan fungsi SHFileOperation untuk melakukan operasi file.

Catatan Pada Windows Vista, penggunaan antarmuka IFileOperation direkomendasikan melalui fungsi ini.
 

Sintaks

typedef struct _SHFILEOPSTRUCTW {
  HWND         hwnd;
  UINT         wFunc;
  PCZZWSTR     pFrom;
  PCZZWSTR     pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCWSTR       lpszProgressTitle;
} SHFILEOPSTRUCTW, *LPSHFILEOPSTRUCTW;

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 dari nilai berikut:

FO_COPY

Salin file yang ditentukan dalam anggota pFrom ke lokasi yang ditentukan dalam anggota pTo .

FO_DELETE

Hapus file yang ditentukan dalam pFrom.

FO_MOVE

Pindahkan file yang ditentukan dalam pFrom ke lokasi yang ditentukan dalam pTo.

FO_RENAME

Ganti nama file yang ditentukan dalam pFrom. Anda tidak dapat menggunakan bendera ini untuk mengganti nama beberapa file dengan satu panggilan fungsi. Gunakan FO_MOVE sebagai gantinya.

pFrom

Jenis: PCZZTSTR

Catatan String ini harus dihentikan dua kali null.
 
Penunjuk ke satu atau beberapa nama file sumber. Nama-nama ini harus menjadi jalur yang sepenuhnya memenuhi syarat untuk mencegah hasil yang tidak terduga.

Karakter kartubebas MS-DOS standar, seperti "*", hanya diizinkan 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

Catatan String ini harus dihentikan dua kali null.
 
Penunjuk ke file tujuan atau nama direktori. Parameter ini harus diatur ke NULL jika tidak digunakan. Karakter kartubebas tidak diperbolehkan. Penggunaannya akan menyebabkan hasil yang tidak dapat diprediksi.

Seperti pFrom, anggota pTo juga merupakan string yang dihentikan dua null dan ditangani dengan cara yang sama. Namun, pTo harus memenuhi spesifikasi berikut:

  • 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 informasi urungkan, jika memungkinkan.

Sebelum Windows Vista, operasi dapat dibatalkan hanya dari proses yang sama yang melakukan operasi asli.

Di Windows Vista dan sistem yang lebih baru, cakupan pembatasan adalah sesi pengguna. Setiap proses yang berjalan dalam sesi pengguna dapat membatalkan operasi lain. Status batalkan diadakan dalam proses Explorer.exe, dan selama proses itu berjalan, ia dapat mengoordinasikan fungsi urungkan.

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 menentukan beberapa file tujuan (satu untuk setiap file sumber dalam pFrom) daripada satu direktori di mana semua file sumber akan disetorkan.

FOF_NOCONFIRMATION

Tanggapi dengan Ya untuk Semua untuk kotak dialog apa pun yang ditampilkan.

FOF_NOCONFIRMMKDIR

Jangan meminta 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 anggota hNameMappings . 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: LPVOID

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 yang dihentikan null. Anggota ini hanya digunakan jika fFlags menyertakan bendera FOF_SIMPLEPROGRESS .

Keterangan

Penting Anda harus memastikan bahwa jalur sumber dan tujuan dihentikan dua kali null. String normal berakhir hanya dalam satu karakter null. Jika Anda meneruskan nilai tersebut di anggota sumber atau tujuan, fungsi tidak akan menyadari ketika telah mencapai akhir string dan akan terus membaca dalam memori sampai datang ke nilai null ganda acak. Ini setidaknya dapat menyebabkan buffer diserbu, dan mungkin penghapusan data yang tidak terkait yang tidak diinginkan.
 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

Untuk mempertanggungjawabkan dua karakter null yang mengakhiri, pastikan untuk membuat buffer yang cukup besar untuk menahan MAX_PATH (yang biasanya mencakup karakter null tunggal yang mengakhiri) ditambah 1.

Tidak dapat dilebih-lebihkan bahwa jalur Anda harus selalu menjadi jalur penuh. Jika anggota pFrom atau pTo adalah nama yang tidak memenuhi syarat, direktori saat ini diambil dari drive global saat ini dan pengaturan direktori seperti yang dikelola oleh fungsi GetCurrentDirectory dan SetCurrentDirectory .

Jika Anda tidak memberikan jalur lengkap, fakta berikut menjadi berkaitan:

  • Kurangnya jalur sebelum nama file tidak menunjukkan ke 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 adalah seluruh proses, dan dapat diubah dari utas lain saat operasi dijalankan. Jika itu terjadi, hasil SHFileOperation tidak akan dapat diprediksi.

Jika pFrom diatur ke nama file tanpa jalur lengkap, menghapus file dengan FO_DELETE tidak memindahkannya ke Keranjang Sampah, bahkan jika 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, hNameMappings menunjuk ke int diikuti dengan array struktur ANSI SHNAMEMAPPING . Untuk aplikasi Unicode, hNameMappings menunjuk ke int diikuti oleh array struktur Unicode SHNAMEMAPPING . Namun, pada Microsoft Windows NT 4.0 dan yang lebih baru, SHFileOperationselalu mengembalikan handel ke sekumpulan struktur SHNAMEMAPPING Unicode. Jika Anda ingin aplikasi berfungsi dengan semua versi Windows, aplikasi harus menggunakan kode bersyarah untuk menangani pemetaan nama. Contohnya:

x = SHFileOperation(&shop);

if (fWin9x) 
    HandleAnsiNameMappings(shop.hNameMappings);
else 
    HandleUnicodeNameMappings(shop.hNameMappings);

Perlakukan hNameMappings sebagai penunjuk ke struktur yang anggotanya adalah nilai UINT diikuti oleh penunjuk ke array struktur SHNAMEMAPPING , seperti yang terlihat dalam deklarasinya:

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

Nilai UINT menunjukkan jumlah struktur SHNAMEMAPPING dalam array. Setiap struktur SHNAMEMAPPING berisi jalur lama dan baru untuk salah satu file yang diganti namanya.

Catatan Handel harus dikosongkan dengan SHFreeNameMappings.
 

Catatan

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

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Header shellapi.h