Menerapkan Antarmuka Objek Folder Dasar

Artikel
06/13/2023

Prosedur untuk menerapkan ekstensi namespace mirip dengan untuk objek Model Objek Komponen (COM) dalam proses lainnya. Semua ekstensi harus mendukung tiga antarmuka utama yang menyediakan Windows Explorer dengan informasi dasar yang diperlukan untuk menampilkan folder ekstensi dalam tampilan pohon. Namun, untuk memanfaatkan sepenuhnya kemampuan Windows Explorer, ekstensi Anda juga harus mengekspos satu atau beberapa antarmuka opsional yang mendukung fitur yang lebih canggih, seperti menu pintasan atau seret dan letakkan, dan menyediakan tampilan folder.

Dokumen ini membahas cara mengimplementasikan antarmuka utama dan opsional yang dipanggil Windows Explorer untuk informasi tentang konten ekstensi Anda. Untuk diskusi tentang cara menerapkan tampilan folder dan cara mengkustomisasi Windows Explorer, lihat Menerapkan Tampilan Folder.

Implementasi dan Pendaftaran Dasar
- Mendaftarkan Ekstensi
Menangani PIDL
Menerapkan Antarmuka Utama
Menerapkan Antarmuka Opsional
Bekerja Dengan Implementasi Tampilan Folder Shell Default

Implementasi dan Pendaftaran Dasar

Sebagai server COM dalam proses, DLL Anda harus mengekspos beberapa fungsi dan antarmuka standar:

Fungsi dan antarmuka ini diimplementasikan dengan cara yang sama seperti untuk sebagian besar objek COM lainnya. Untuk detailnya, lihat dokumentasi COM.

Mendaftarkan Ekstensi

Seperti semua objek COM, Anda harus membuat GUID pengidentifikasi kelas (CLSID) untuk ekstensi Anda. Daftarkan objek dengan membuat subkunci HKEY_CLASSES_ROOT\CLSID bernama untuk CLSID ekstensi Anda. DLL harus didaftarkan sebagai server dalam proses dan harus menentukan model utas apartemen. Anda dapat menyesuaikan perilaku folder akar ekstensi dengan menambahkan berbagai subkunci dan nilai ke kunci CLSID ekstensi.

Beberapa nilai ini hanya berlaku untuk ekstensi dengan titik persimpangan virtual. Nilai-nilai ini tidak berlaku untuk ekstensi yang titik persimpangannya adalah folder sistem file. Untuk diskusi lebih lanjut, lihat Menentukan Lokasi Ekstensi Namespace. Untuk mengubah perilaku ekstensi dengan titik persimpangan virtual, tambahkan satu atau beberapa nilai berikut ke kunci CLSID ekstensi:

InginFORPARSING. Nama penguraian untuk ekstensi dengan titik persimpangan virtual biasanya akan memiliki formulir ::{GUID}. Ekstensi jenis ini biasanya berisi item virtual. Namun, beberapa ekstensi, seperti Dokumen Saya, sebenarnya sesuai dengan folder sistem file, meskipun mereka memiliki titik persimpangan virtual. Jika ekstensi Anda mewakili objek sistem file dengan cara ini, Anda dapat mengatur nilai WantsFORPARSING. Windows Explorer kemudian akan meminta nama penguraian folder akar Anda dengan memanggil metode IShellFolder::GetDisplayNameOf objek folder dengan uFlags diatur ke SHGDN_FORPARSING dan pidl diatur ke satu penunjuk kosong ke daftar pengidentifikasi item (PIDL). PIDL kosong hanya berisi terminator. Metode Anda kemudian harus mengembalikan nama penguraian folder akar ::{GUID}.
HideFolderVerbs. Kata kerja yang terdaftar di bawah Folder HKEY_CLASSES_ROOT\biasanya dikaitkan dengan semua ekstensi. Mereka muncul di menu pintasan ekstensi dan dapat dipanggil oleh ShellExecute. Untuk mencegah salah satu kata kerja ini dikaitkan dengan ekstensi Anda, atur nilai HideFolderVerbs.
SembunyikanAsDelete. Jika pengguna mencoba menghapus ekstensi Anda, Windows Explorer akan menyembunyikan ekstensi.
HideAsDeletePerUser. Nilai ini memiliki efek yang sama dengan HideAsDelete tetapi berdasarkan per pengguna. Ekstensi ini disembunyikan hanya untuk pengguna yang telah mencoba menghapusnya. Ekstensi ini terlihat oleh semua pengguna lain.
QueryForOverlay. Atur nilai ini untuk menunjukkan bahwa ikon folder akar dapat memiliki overlay ikon. Objek folder harus mendukung antarmuka IShellIconOverlay. Sebelum Windows Explorer menampilkan ikon folder akar, ini akan meminta ikon overlay dengan memanggil salah satu dari dua metode IShellIconOverlay dengan pidlItem diatur ke PIDL kosong.

Nilai dan subkey yang tersisa berlaku untuk semua ekstensi:

Untuk menentukan nama tampilan folder titik persimpangan ekstensi, atur nilai default subkunci CLSID ekstensi ke string yang sesuai.
Saat kursor mengarahkan kursor ke folder, infotip biasanya ditampilkan yang menjelaskan konten folder. Untuk memberikan infotip untuk folder akar ekstensi Anda, buat nilai InfoTip REG_SZ untuk kunci CLSID ekstensi, dan atur ke string yang sesuai.
Untuk menentukan ikon kustom untuk folder akar ekstensi Anda, buat subkunci subkunci CLSID ekstensi bernama DefaultIcon. Atur nilai default DefaultIcon ke nilai REG_SZ yang berisi nama file yang berisi ikon, diikuti dengan koma, diikuti dengan tanda minus, diikuti oleh indeks ikon dalam file tersebut.
Secara default, menu pintasan folder akar ekstensi Anda akan berisi item yang ditentukan di bawah HKEY_CLASSES_ROOT\Folder. Item Hapus, Ganti Nama, dan Properti ditambahkan jika Anda telah mengatur bendera SFGAO_XXX yang sesuai. Anda dapat menambahkan item lain ke menu pintasan folder akar, atau menimpa item yang ada, sebanyak yang Anda lakukan untuk jenis file. Buat subkunci Shell di bawah kunci CLSID ekstensi, dan tentukan perintah seperti yang dibahas di Memperluas Menu Pintasan.
Jika Anda memerlukan cara yang lebih fleksibel untuk menangani menu pintasan folder akar, Anda dapat menerapkan penangan menu pintasan. Untuk mendaftarkan handler menu pintasan, buat kunci ShellEx di bawah kunci CLSID ekstensi. Daftarkan CLSID handler seperti yang Anda lakukan untuk Create Shell Extension Handler konvensional.
Untuk menambahkan halaman ke lembar properti Properti folder akar, berikan folder atribut SFGAO_HASPROPSHEET dan terapkan handler lembar properti. Untuk mendaftarkan handler lembar properti, buat kunci ShellEx di bawah kunci CLSID ekstensi. Daftarkan CLSID handler seperti yang Anda lakukan untuk Create Shell Extension Handler konvensional.
Untuk menentukan atribut folder akar, tambahkan subkunci ShellFolder ke subkunci CLSID ekstensi. Buat nilai Atribut, dan atur ke kombinasi bendera SFGAO_XXX yang sesuai.

Tabel berikut mencantumkan beberapa atribut yang umum digunakan untuk folder akar.

Bendera	Nilai	Deskripsi
SFGAO_FOLDER	0x20000000	Folder akar ekstensi berisi satu atau beberapa item.
SFGAO_HASSUBFOLDER	0x80000000	Folder akar ekstensi berisi satu atau beberapa subfolder. Windows Explorer akan menempatkan tanda plus ( + ) di samping ikon folder.
SFGAO_CANDELETE	0x00000020	Folder akar ekstensi dapat dihapus oleh pengguna. Menu pintasan folder akan memiliki item Hapus . Bendera ini harus diatur untuk titik persimpangan yang ditempatkan di bawah salah satu folder virtual.
SFGAO_CANRENAME	0x00000010	Folder akar ekstensi dapat diganti namanya oleh pengguna. Menu pintasan folder akan memiliki item Ganti Nama .
SFGAO_HASPROPSHEET	0x00000040	Folder akar ekstensi memiliki lembar properti Properti . Menu pintasan folder akan memiliki item Properti . Untuk menyediakan lembar properti, Anda harus menerapkan handler lembar properti. Daftarkan handler di bawah kunci CLSID ekstensi, seperti yang dibahas sebelumnya.

Contoh berikut menunjukkan entri registri CLSID untuk ekstensi dengan nama tampilan MyExtension. Ekstensi memiliki ikon kustom yang terkandung dalam DLL ekstensi dengan indeks 1. Atribut SFGAO_FOLDER, SFGAO_HASSUBFOLDER, dan SFGAO_CANDELETE diatur.

HKEY_CLASSES_ROOT
   CLSID
      {Extension CLSID}
         (Default) = MyExtension
         InfoTip = Some appropriate text
      DefaultIcon
         (Default) = c:\MyDir\MyExtension.dll,-1
      InProcServer32
         (Default) = c:\MyDir\MyExtension.dll
         ThreadingModel = Apartment
      ShellFolder
         Attributes = 0xA00000020

Menangani PIDL

Setiap item di namespace Shell harus memiliki PIDL yang unik. Windows Explorer menetapkan PIDL ke folder akar Anda dan meneruskan nilai ke ekstensi Anda selama inisialisasi. Ekstensi Anda kemudian bertanggung jawab untuk menetapkan PIDL yang dibuat dengan benar ke setiap objeknya dan menyediakan PIDL tersebut ke Windows Explorer berdasarkan permintaan. Saat Shell menggunakan PIDL untuk mengidentifikasi salah satu objek ekstensi Anda, ekstensi Anda harus dapat menafsirkan PIDL dan mengidentifikasi objek tertentu. Ekstensi Anda juga harus menetapkan nama tampilan dan nama penguraian untuk setiap objek. Karena PIDL digunakan oleh hampir setiap antarmuka folder, ekstensi biasanya mengimplementasikan satu manajer PIDL untuk menangani semua tugas ini.

Istilah PIDL adalah kependek dari struktur ITEMIDLIST atau penunjuk ke struktur seperti itu, tergantung pada konteks. Seperti yang dinyatakan, struktur ITEMIDLIST memiliki satu anggota, struktur SHITEMID. Struktur ITEMIDLIST objek sebenarnya adalah array yang dikemas dari dua atau lebih struktur SHITEMID. Urutan struktur ini mendefinisikan jalur melalui namespace layanan, dengan cara yang sama seperti c:\MyDirectory\MyFile mendefinisikan jalur melalui sistem file. Biasanya, PIDL objek akan terdiri dari serangkaian struktur SHITEMID yang sesuai dengan folder yang menentukan jalur namespace, diikuti oleh struktur SHITEMID objek, diikuti oleh terminator.

Terminator adalah struktur SHITEMID, dengan anggota cb diatur ke NULL. Terminator diperlukan karena jumlah struktur SHITEMID dalam PIDL objek tergantung pada lokasi objek di namespace Shell, dan titik awal jalur. Selain itu, ukuran berbagai struktur SHITEMID dapat bervariasi. Ketika Anda menerima PIDL, Anda tidak memiliki cara sederhana untuk menentukan ukurannya atau bahkan jumlah total struktur SHITEMID . Sebagai gantinya, Anda harus "berjalan" array yang dikemas, struktur menurut struktur, sampai Anda mencapai terminator.

Untuk membuat PIDL, aplikasi Anda perlu:

Buat struktur SHITEMID untuk setiap objeknya.
Merakit struktur SHITEMID yang relevan ke dalam PIDL.

Membuat Struktur SHITEMID

Struktur SHITEMID objek secara unik mengidentifikasi objek dalam foldernya. Bahkan, jenis PIDL yang digunakan oleh banyak metode IShellFolder hanya terdiri dari struktur SHITEMID objek, diikuti oleh terminator. Definisi struktur SHITEMID adalah:

typedef struct _SHITEMID { 
    USHORT cb; 
    BYTE   abID[1]; 
} SHITEMID, * LPSHITEMID;

Anggota abID adalah pengidentifikasi objek. Karena panjang abID tidak ditentukan dan dapat bervariasi, anggota cb diatur ke ukuran struktur SHITEMID, dalam byte.

Karena panjang atau konten abID tidak distandarkan, Anda dapat menggunakan skema apa pun yang ingin Anda tetapkan nilai abID ke objek Anda. Satu-satunya persyaratan adalah Anda tidak dapat memiliki dua objek dalam folder yang sama dengan nilai yang identik. Namun, karena alasan performa, struktur SHITEMID Anda harus selaras dengan DWORD. Dengan kata lain, Anda harus membangun nilai abID Anda sehingga cb adalah kelipatan integral dari 4.

Biasanya, abID menunjuk ke struktur yang ditentukan ekstensi. Selain ID objek, struktur ini sering digunakan untuk menyimpan berbagai informasi terkait, seperti jenis atau atribut objek. Objek folder ekstensi Anda kemudian dapat dengan cepat mengekstrak informasi dari PIDL alih-alih harus memintanya.

Catatan

Salah satu aspek terpenting dalam merancang struktur data untuk PIDL adalah membuat struktur tetap stabil dan dapat diangkut. Dalam konteks PIDL, arti dari istilah-istilah ini adalah:

Tetap stabil. Sistem sering menempatkan PIDL di berbagai jenis penyimpanan jangka panjang, seperti file pintasan. Kemudian dapat memulihkan PIDL ini dari penyimpanan nanti, mungkin setelah sistem di-boot ulang. PIDL yang telah dipulihkan dari penyimpanan masih harus valid dan bermakna bagi ekstensi Anda. Persyaratan ini berarti, misalnya, Anda tidak boleh menggunakan pointer atau handel dalam struktur PIDL Anda. PIDL yang berisi jenis data ini biasanya tidak akan berarti ketika sistem kemudian memulihkannya dari penyimpanan.
Diangkut. PIDL harus tetap bermakna ketika diangkut dari satu komputer ke komputer lainnya. Misalnya, PIDL dapat ditulis ke file pintasan, disalin ke disket, dan diangkut ke komputer lain. PIDL itu harus tetap bermakna bagi ekstensi Anda yang berjalan di komputer kedua. Misalnya, untuk memastikan bahwa PIDL Anda dapat diangkut, gunakan karakter ANSI atau Unicode secara eksplisit. Hindari jenis data seperti TCHAR atau LPTSTR. Jika Anda menggunakan jenis data tersebut, PIDL yang dibuat pada komputer yang menjalankan versi Unicode ekstensi Anda tidak akan dapat dibaca oleh versi ANSI ekstensi yang berjalan di komputer lain.

Deklarasi berikut menunjukkan contoh sederhana struktur data.

typedef struct tagMYPIDLDATA {
  USHORT cb;
  DWORD dwType;
  WCHAR wszDisplayName[40];
} MYPIDLDATA, *LPMYPIDLDATA;

Anggota cb diatur ke ukuran struktur MYPIDLDATA . Anggota ini menjadikan MYPIDLDATA struktur SHITEMID yang valid, dalam dan dari dirinya sendiri. Anggota lainnya setara dengan anggota struktur SHITEMID yang abID dan menyimpan data privat. Anggota dwType adalah nilai yang ditentukan ekstensi yang menunjukkan jenis objek. Untuk contoh ini, dwType diatur ke TRUE untuk folder dan FALSE jika tidak. Anggota ini memungkinkan Anda, misalnya, untuk dengan cepat menentukan apakah objek tersebut adalah folder atau tidak. Anggota wszDisplayName berisi nama tampilan objek. Karena Anda tidak akan menetapkan nama tampilan yang sama ke dua objek berbeda dalam folder yang sama, nama tampilan juga berfungsi sebagai ID objek. Dalam contoh ini, wszDisplayName diatur ke 40 karakter untuk menjamin bahwa struktur SHITEMID akan selaras dengan DWORD. Untuk membatasi ukuran PIDL, Anda dapat menggunakan array karakter panjang variabel dan menyesuaikan nilai cb yang sesuai. Pad string tampilan dengan karakter '\0' yang cukup untuk mempertahankan perataan DWORD struktur. Anggota lain yang mungkin berguna untuk dimasukkan ke dalam struktur termasuk ukuran objek, atribut, atau nama penguraian.

Membuat PIDL

Setelah menentukan struktur SHITEMID untuk objek Anda, Anda kemudian dapat menggunakannya untuk membangun PIDL. PIDL dapat dibangun untuk berbagai tujuan, tetapi sebagian besar tugas menggunakan salah satu dari dua jenis PIDL. PIDL tingkat tunggal yang paling sederhana, mengidentifikasi objek relatif terhadap folder induknya. Jenis PIDL ini digunakan oleh banyak metode IShellFolder. PIDL tingkat tunggal berisi struktur SHITEMID objek, diikuti oleh terminator. PIDL yang sepenuhnya memenuhi syarat menentukan jalur melalui hierarki namespace dari desktop ke objek. Jenis PIDL ini dimulai di desktop dan berisi satu struktur SHITEMID untuk setiap folder di jalur, diikuti oleh objek dan terminator. PIDL yang sepenuhnya memenuhi syarat secara unik mengidentifikasi objek dalam seluruh namespace Shell.

Cara paling sederhana untuk membangun PIDL adalah dengan bekerja langsung dengan struktur ITEMIDLIST itu sendiri. Buat struktur ITEMIDLIST, tetapi alokasikan cukup memori untuk menyimpan semua struktur SHITEMID. Alamat struktur ini akan menunjuk ke struktur SHITEMID awal. Tentukan nilai untuk anggota struktur awal ini, lalu tambahkan struktur SHITEMID tambahan sebanyak yang Anda butuhkan, dalam urutan yang sesuai. Prosedur berikut menguraikan cara membuat PIDL tingkat tunggal. Ini berisi dua struktur SHITEMID — struktur MYPIDLDATA diikuti oleh terminator:

Gunakan fungsi CoTaskMemAlloc untuk mengalokasikan memori untuk PIDL. Alokasikan memori yang cukup untuk data privat Anda ditambah USHORT (dua byte) untuk terminator. Transmisikan hasilnya ke LPMYPIDLDATA.
Atur anggota cb dari struktur MYPIDLDATA pertama ke ukuran struktur tersebut. Untuk contoh ini, Anda akan mengatur cb ke sizeof(MYPIDLDATA). Jika Anda ingin menggunakan struktur panjang variabel, Anda harus menghitung nilai cb.
Tetapkan nilai yang sesuai ke anggota data privat.
Hitung alamat struktur SHITEMID berikutnya. Transmisikan alamat struktur MYPIDLDATA saat ini ke LPBYTE, dan tambahkan nilai tersebut ke nilai cb yang ditentukan di langkah 3.
Dalam hal ini, struktur SHITEMID berikutnya adalah terminator. Atur anggota cb struktur ke nol.

Untuk PIDL yang lebih panjang, alokasikan memori yang cukup dan ulangi langkah 3-5 untuk setiap struktur SHITEMID tambahan.

Fungsi sampel berikut mengambil jenis objek dan nama tampilan dan mengembalikan PIDL tingkat tunggal objek. Fungsi ini mengasumsikan bahwa nama tampilan, termasuk karakter null yang dihentikan, tidak melebihi jumlah karakter yang dideklarasikan untuk struktur MYPIDLDATA. Jika asumsi tersebut ternyata salah, fungsi StringCbCopyW akan memotong nama tampilan. Variabel g_pMalloc adalah pointer IMalloc yang dibuat di tempat lain dan disimpan dalam variabel global.

LPITEMIDLIST CreatePIDL(DWORD dwType, LPCWSTR pwszDisplayName)
{
    LPMYPIDLDATA   pidlOut;
    USHORT         uSize;

    pidlOut = NULL;

    //Calculate the size of the MYPIDLDATA structure.
    uSize = sizeof(MYPIDLDATA);

    // Allocate enough memory for the PIDL to hold a MYPIDLDATA structure 
    // plus the terminator
    pidlOut = (LPMYPIDLDATA)m_pMalloc->Alloc(uSize + sizeof(USHORT));

    if(pidlOut)
    {
       //Assign values to the members of the MYPIDLDATA structure
       //that is the PIDL's first SHITEMID structure
       pidlOut->cb = uSize;
       pidlOut->dwType = dwType;
       hr = StringCbCopyW(pidlOut->wszDisplayName, 
                          sizeof(pidlOut->wszDisplayName), pwszDisplayName);
       
       // TODO: Add error handling here to verify the HRESULT returned 
       // by StringCbCopyW.

       //Advance the pointer to the start of the next SHITEMID structure.
       pidlOut = (LPMYPIDLDATA)((LPBYTE)pidlOut + pidlOut->cb);

       //Create the terminating null character by setting cb to 0.
       pidlOut->cb = 0;
    }

    return pidlOut;

PIDL yang sepenuhnya memenuhi syarat harus memiliki struktur SHITEMID untuk setiap objek dari desktop ke objek Anda. Ekstensi Anda menerima PIDL yang sepenuhnya memenuhi syarat untuk folder akar Anda ketika Shell memanggil IPersistFolder::Initialize. Untuk membuat PIDL yang sepenuhnya memenuhi syarat untuk objek, ambil PIDL yang telah ditetapkan Shell ke folder akar Anda, dan tambahkan struktur SHITEMID yang diperlukan untuk membawa Anda dari folder akar ke objek.

Menginterpretasikan PIDL

Ketika Shell atau aplikasi memanggil salah satu antarmuka ekstensi Anda untuk meminta informasi tentang objek, biasanya akan mengidentifikasi objek oleh PIDL. Beberapa metode, seperti IShellFolder::GetUIObjectOf, menggunakan PIDL yang relatif terhadap folder induk dan mudah ditafsirkan. Namun, ekstensi Anda mungkin juga akan menerima PIDL yang sepenuhnya memenuhi syarat. Manajer PIDL Anda kemudian harus menentukan objek mana yang dimaksud pidl.

Apa yang mempersulit tugas mengaitkan objek dengan PIDL yang sepenuhnya memenuhi syarat adalah bahwa satu atau beberapa struktur SHITEMID awal di PIDL mungkin milik objek yang terletak di luar ekstensi Anda di namespace Shell. Anda tidak memiliki cara untuk menafsirkan arti anggota abID dari struktur tersebut. Apa yang harus dilakukan ekstensi Anda adalah "berjalan" daftar struktur SHITEMID , sampai Anda mencapai struktur yang sesuai dengan folder akar Anda. Sejak saat itu, Anda akan tahu cara menginterpretasikan informasi dalam struktur SHITEMID .

Untuk berjalan di PIDL, ambil nilai cb pertama dan tambahkan ke alamat PIDL untuk memajukan pointer ke awal struktur SHITEMID berikutnya. Kemudian akan menunjuk ke anggota cb struktur itu, yang dapat Anda gunakan untuk memajukan pointer ke awal struktur SHITEMID berikutnya, dan sebagainya. Setiap kali Anda memajukan penunjuk, periksa struktur SHITEMID untuk menentukan apakah Anda telah mencapai akar namespace ekstensi Anda.

Menerapkan Antarmuka Utama

Seperti halnya semua objek COM, mengimplementasikan ekstensi sebagian besar adalah masalah mengimplementasikan kumpulan antarmuka. Bagian ini membahas tiga antarmuka utama yang harus diimplementasikan oleh semua ekstensi. Mereka digunakan untuk inisialisasi dan untuk menyediakan Windows Explorer dengan informasi dasar tentang konten ekstensi. Antarmuka ini, ditambah tampilan folder, adalah semua yang diperlukan untuk ekstensi fungsional. Namun, untuk sepenuhnya mengeksploitasi fitur Windows Explorer, sebagian besar ekstensi juga mengimplementasikan satu atau beberapa antarmuka opsional.

Antarmuka IPersistFolder

Antarmuka IPersistFolder dipanggil untuk menginisialisasi objek folder baru. Metode IPersistFolder::Initialize menetapkan PIDL yang sepenuhnya memenuhi syarat ke objek baru. Simpan PIDL ini untuk digunakan nanti. Misalnya, objek folder harus menggunakan PIDL ini untuk membangun PIDL yang sepenuhnya memenuhi syarat untuk anak objek. Pembuat objek folder juga dapat memanggil IPersist::GetClassID untuk meminta CLSID objek.

Biasanya, objek folder dibuat dan diinisialisasi oleh metode IShellFolder::BindToObject folder induknya. Namun, ketika pengguna menelusuri ekstensi Anda, Windows Explorer membuat dan menginisialisasi objek folder akar ekstensi. PIDL yang diterima objek folder akar melalui IPersistFolder::Initialize berisi jalur dari desktop ke folder akar yang Anda perlukan untuk membuat PIDL yang sepenuhnya memenuhi syarat untuk ekstensi Anda.

Antarmuka IShellFolder

Shell memperlakukan ekstensi sebagai kumpulan objek folder yang diurutkan secara hierarkis. Antarmuka IShellFolder adalah inti dari implementasi ekstensi apa pun. Ini mewakili objek folder dan menyediakan Windows Explorer dengan banyak informasi yang diperlukan untuk menampilkan konten folder.

IShellFolder biasanya adalah satu-satunya antarmuka folder selain IPersistFolder yang langsung diekspos oleh objek folder. Sementara Windows Explorer menggunakan berbagai antarmuka yang diperlukan dan opsional untuk mendapatkan informasi tentang isi folder, ia mendapatkan pointer ke antarmuka tersebut melalui IShellFolder.

Windows Explorer mendapatkan CLSID folder akar ekstensi Anda dengan berbagai cara. Untuk detailnya, lihat Menentukan Lokasi Ekstensi Namespace atau Menampilkan Tampilan Mandiri Ekstensi Namespace. Windows Explorer kemudian menggunakan CLSID tersebut untuk membuat dan menginisialisasi instans folder akar dan kueri untuk antarmuka IShellFolder. Ekstensi Anda membuat objek folder untuk mewakili folder akar dan mengembalikan antarmuka IShellFolder objek. Sebagian besar sisa interaksi antara ekstensi Anda dan Windows Explorer kemudian terjadi melalui IShellFolder. Windows Explorer memanggil IShellFolder untuk:

Minta objek yang dapat menghitung konten folder akar.
Dapatkan berbagai jenis informasi tentang konten folder akar.
Minta objek yang mengekspos salah satu antarmuka opsional. Antarmuka tersebut kemudian dapat dikueri untuk informasi tambahan, seperti ikon atau menu pintasan.
Minta objek folder yang mewakili subfolder folder akar.

Saat pengguna membuka subfolder folder akar, Windows Explorer memanggil IShellFolder::BindToObject. Ekstensi Anda membuat dan menginisialisasi objek folder baru untuk mewakili subfolder dan mengembalikan antarmuka IShellFolder-nya. Windows Explorer kemudian memanggil antarmuka ini untuk berbagai jenis informasi, dan sebagainya hingga pengguna memutuskan untuk menavigasi ke tempat lain di namespace Shell atau menutup Windows Explorer.

Sisa bagian ini secara singkat membahas metode IShellFolder yang lebih penting dan cara mengimplementasikannya.

EnumObjects

Sebelum menampilkan isi folder dalam tampilan pohon, Windows Explorer harus terlebih dahulu menentukan isi folder dengan memanggil metode IShellFolder::EnumObjects. Metode ini membuat objek enumerasi OLE standar yang mengekspos antarmuka IEnumIDList dan mengembalikan penunjuk antarmuka tersebut. Antarmuka IEnumIDList memungkinkan Windows Explorer untuk mendapatkan PIDL dari semua objek yang terkandung oleh folder. PIDL ini kemudian digunakan untuk mendapatkan informasi tentang objek yang terkandung oleh folder. Untuk detail lebih lanjut, lihat Antarmuka IEnumIDList.

Catatan

Metode IEnumIDList::Next hanya boleh mengembalikan PIDL yang relatif terhadap folder induk. PIDL hanya boleh berisi struktur SHITEMID objek, diikuti oleh terminator.

CreateViewObject

Sebelum konten folder ditampilkan, Windows Explorer memanggil metode ini untuk meminta penunjuk ke antarmuka IShellView. Antarmuka ini digunakan oleh Windows Explorer untuk mengelola tampilan folder. Buat objek tampilan folder dan kembalikan antarmuka IShellView-nya.

Metode IShellFolder::CreateViewObject juga dipanggil untuk meminta salah satu antarmuka opsional, seperti IContextMenu, untuk folder itu sendiri. Implementasi Anda dari metode ini harus membuat objek yang mengekspos antarmuka yang diminta dan mengembalikan penunjuk antarmuka. Jika Windows Explorer memerlukan antarmuka opsional untuk salah satu objek yang dimuat oleh folder, itu akan memanggil IShellFolder::GetUIObjectOf.

GetUIObjectOf

Meskipun informasi dasar tentang konten folder tersedia melalui metode IShellFolder , ekstensi Anda juga dapat menyediakan Windows Explorer dengan berbagai jenis informasi tambahan. Misalnya, Anda dapat menentukan ikon untuk konten folder atau menu pintasan objek. Windows Explorer memanggil metode IShellFolder::GetUIObjectOf untuk mencoba mengambil informasi tambahan tentang objek yang dimuat oleh folder. Windows Explorer menentukan objek mana yang diinginkan informasinya, dan IID antarmuka yang relevan. Objek folder kemudian membuat objek yang mengekspos antarmuka yang diminta dan mengembalikan penunjuk antarmuka.

Jika ekstensi Anda memungkinkan pengguna mentransfer objek dengan seret dan letakkan atau clipboard, Windows Explorer akan memanggil IShellFolder::GetUIObjectOf untuk meminta antarmuka IDataObject atau IDropTarget. Untuk detailnya, lihat Mentransfer Objek Shell dengan Seret dan Letakkan dan Clipboard.

Windows Explorer memanggil IShellFolder::CreateViewObject ketika menginginkan jenis informasi yang sama tentang folder itu sendiri.

BindToObject

Windows Explorer memanggil metode IShellFolder::BindToObject saat pengguna mencoba membuka salah satu subfolder ekstensi Anda. Jika riid diatur ke IID_IShellFolder, Anda harus membuat dan menginisialisasi objek folder yang mewakili subfolder dan mengembalikan antarmuka IShellFolder objek.

Catatan

Saat ini, Windows Explorer memanggil metode ini hanya untuk meminta antarmuka IShellFolder. Namun, jangan berasumsi bahwa ini akan selalu terjadi. Anda harus selalu memeriksa nilai riid sebelum melanjutkan.

GetDisplayNameOf

Windows Explorer memanggil metode IShellFolder::GetDisplayNameOf untuk mengonversi PIDL salah satu objek folder menjadi nama. PIDL tersebut harus relatif terhadap folder induk objek. Dengan kata lain, ini harus berisi struktur SHITEMID non-NULL tunggal. Karena ada lebih dari satu cara yang mungkin untuk memberi nama objek, Windows Explorer menentukan jenis nama dengan mengatur satu atau beberapa bendera SHGDNF dalam parameter uFlags. Salah satu dari dua nilai, SHGDN_NORMAL atau SHGDN_INFOLDER, akan diatur untuk menentukan apakah nama harus relatif terhadap folder atau relatif terhadap desktop. Salah satu dari tiga nilai lainnya, SHGDN_FOREDITING, SHGDN_FORADDRESSBAR, atau SHGDN_FORPARSING, dapat diatur untuk menentukan nama yang akan digunakan.

Anda harus mengembalikan nama dalam bentuk struktur STRRET . Jika SHGDN_FOREDITING, SHGDN_FORADDRESSBAR, dan SHGDN_FORPARSING tidak diatur, kembalikan nama tampilan objek. Jika bendera SHGDN_FORPARSING diatur, Windows Explorer meminta nama penguraian. Nama penguraian diteruskan ke IShellFolder::P arseDisplayName untuk mendapatkan PIDL objek, meskipun mungkin terletak satu atau beberapa tingkat di bawah folder saat ini dalam hierarki namespace. Misalnya, nama penguraian objek sistem file adalah jalurnya. Anda dapat melewati jalur objek apa pun yang sepenuhnya memenuhi syarat dalam sistem file ke metode IShellFolder::P arseDisplayName desktop, dan itu akan mengembalikan PIDL objek yang sepenuhnya memenuhi syarat.

Meskipun nama penguraian adalah string teks, nama tersebut tidak harus menyertakan nama tampilan. Anda harus menetapkan nama penguraian berdasarkan apa yang akan bekerja paling efisien ketika IShellFolder::P arseDisplayName dipanggil. Misalnya, banyak folder virtual Shell bukan bagian dari sistem file dan tidak memiliki jalur yang sepenuhnya memenuhi syarat. Sebagai gantinya, setiap folder diberi GUID dan nama penguraian mengambil formulir ::{GUID}. Terlepas dari skema apa yang Anda gunakan, itu harus dapat dengan andal "pulang pergi." Misalnya, jika penelepon meneruskan nama penguraian ke IShellFolder::P arseDisplayName untuk mengambil PIDL objek, lalu meneruskan PIDL tersebut ke IShellFolder::GetDisplayNameOf dengan set bendera SHGDN_FORPARSING , pemanggil harus memulihkan nama penguraian asli.

GetAttributesOf

Windows Explorer memanggil metode IShellFolder::GetAttributesOf untuk menentukan atribut satu atau beberapa item yang terkandung oleh objek folder. Nilai cidl memberikan jumlah item dalam kueri, dan aPidl menunjuk ke daftar PIDL mereka.

Karena pengujian untuk beberapa atribut dapat memakan waktu, Windows Explorer biasanya membatasi kueri ke subset bendera yang tersedia dengan mengatur nilainya di rfgInOut. Metode Anda harus menguji hanya atribut yang benderanya diatur dalam rfgInOut. Biarkan bendera yang valid diatur dan kosongkan sisanya. Jika lebih dari satu item disertakan dalam kueri, atur hanya bendera yang berlaku untuk semua item.

Catatan

Atribut harus diatur dengan benar agar item ditampilkan dengan benar. Misalnya, jika item adalah folder yang berisi subfolder, Anda harus mengatur bendera SFGAO_HASSUBFOLDER . Jika tidak, Windows Explorer tidak akan menampilkan + di samping ikon item dalam tampilan pohon.

ParseDisplayName

Metode IShellFolder::P arseDisplayName dalam arti tertentu adalah gambar cermin IShellFolder::GetDisplayNameOf. Penggunaan paling umum dari metode ini adalah mengonversi nama penguraian objek menjadi PIDL terkait. Nama penguraian dapat merujuk ke objek apa pun yang terletak di bawah folder dalam hierarki namespace. PIDL yang dikembalikan relatif terhadap objek folder yang mengekspos metode dan biasanya tidak sepenuhnya memenuhi syarat. Dengan kata lain, meskipun PIDL dapat berisi beberapa struktur SHITEMID , yang pertama adalah objek itu sendiri atau subfolder pertama di jalur dari folder ke objek. Pemanggil harus menambahkan PIDL ini ke PIDL folder yang sepenuhnya memenuhi syarat untuk mendapatkan PIDL yang sepenuhnya memenuhi syarat untuk objek tersebut.

IShellFolder::P arseDisplayName juga dapat dipanggil untuk meminta atribut objek. Karena menentukan semua atribut yang berlaku dapat memakan waktu, pemanggil hanya akan mengatur bendera SFGAO_XXX yang mewakili informasi yang diminati pemanggil. Anda harus menentukan atribut mana yang benar untuk objek, dan menghapus bendera yang tersisa.

Antarmuka IEnumIDList

Ketika Windows Explorer perlu menghitung objek yang dimuat oleh folder, ia memanggil IShellFolder::EnumObjects. Objek folder harus membuat objek enumerasi yang mengekspos antarmuka IEnumIDList dan mengembalikan penunjuk antarmuka tersebut. Windows Explorer kemudian biasanya akan menggunakan IEnumIDList untuk menghitung PIDL dari semua objek yang terkandung oleh folder.

IEnumIDList adalah antarmuka enumerasi OLE standar dan diimplementasikan dengan cara yang biasa. Ingat, bagaimanapun, bahwa PIDL yang Anda kembalikan harus relatif terhadap folder dan hanya berisi struktur SHITEMID objek dan terminator.

Menerapkan Antarmuka Opsional

Ada sejumlah antarmuka Shell opsional yang dapat didukung objek folder ekstensi Anda. Banyak dari mereka, seperti IExtractIcon, memungkinkan Anda untuk menyesuaikan berbagai aspek cara pengguna melihat ekstensi Anda. Lainnya, seperti IDataObject, memungkinkan ekstensi Anda untuk mendukung fitur seperti seret dan letakkan.

Tidak ada antarmuka opsional yang diekspos langsung oleh objek folder. Sebagai gantinya, Windows Explorer memanggil salah satu dari dua metode IShellFolder untuk meminta antarmuka:

Windows Explorer memanggil IShellFolder::GetUIObjectOf objek folder untuk meminta antarmuka salah satu objek yang dimuat oleh folder.
Windows Explorer memanggil IShellFolder::CreateViewObject objek folder untuk meminta antarmuka folder itu sendiri.

Untuk memberikan informasi, objek folder membuat objek yang mengekspos antarmuka yang diminta dan mengembalikan penunjuk antarmuka. Windows Explorer kemudian memanggil antarmuka tersebut untuk mengambil informasi yang diperlukan. Bagian ini membahas antarmuka opsional yang paling umum digunakan.

IExtractIcon

Windows Explorer meminta antarmuka IExtractIcon sebelum menampilkan isi folder. Antarmuka memungkinkan ekstensi Anda menentukan ikon kustom untuk objek yang dimuat oleh folder. Jika tidak, ikon file dan folder standar akan digunakan. Untuk menyediakan ikon kustom, buat objek ekstraksi ikon yang mengekspos IExtractIcon dan kembalikan penunjuk ke antarmuka tersebut. Untuk diskusi lebih lanjut, lihat dokumentasi referensi IExtractIcon atau Membuat Handler Ikon.

IContextMenu

Saat pengguna mengklik kanan objek, Windows Explorer meminta antarmuka IContextMenu. Untuk menyediakan menu pintasan untuk objek Anda, buat objek handler menu dan kembalikan antarmuka IContextMenu-nya.

Prosedur untuk membuat objek penangan menu sangat mirip dengan yang digunakan untuk membuat ekstensi Shell penangan menu. Untuk detailnya, lihat Membuat Penangan Menu Konteks atau referensi IContextMenu, IContextMenu2, atau IContextMenu3.

IQueryInfo

Windows Explorer memanggil antarmuka IQueryInfo untuk mengambil string teks infotip.

IDataObject dan IDropTarget

Ketika objek Anda ditampilkan oleh Windows Explorer, objek folder tidak memiliki cara langsung untuk mengetahui kapan pengguna mencoba memotong, menyalin, atau menyeret objek. Sebagai gantinya, Windows Explorer meminta antarmuka IDataObject. Untuk mengizinkan objek ditransfer, buat objek data dan kembalikan penunjuk ke antarmuka IDataObject-nya.

Demikian pula, pengguna mungkin mencoba menghilangkan objek data pada representasi Windows Explorer dari salah satu objek Anda, seperti ikon atau jalur bilah alamat. Windows Explorer kemudian meminta antarmuka IDropTarget. Untuk memungkinkan objek data dihilangkan, buat objek yang mengekspos antarmuka IDropTarget dan kembalikan penunjuk antarmuka.

Menangani transfer data adalah salah satu aspek yang lebih sulit dalam menulis ekstensi namespace layanan. Untuk diskusi terperinci, lihat Mentransfer Objek Shell dengan Drag-and-Drop dan Clipboard.

Bekerja Dengan Implementasi Tampilan Folder Shell Default

Sumber data yang menggunakan objek tampilan folder Shell default (DefView) harus menerapkan antarmuka ini:

Secara opsional, mereka juga dapat menerapkan IPersistFolder3.

Bagikan melalui

Menerapkan Antarmuka Objek Folder Dasar

Implementasi dan Pendaftaran Dasar

Mendaftarkan Ekstensi

Menangani PIDL

Membuat Struktur SHITEMID

Membuat PIDL

Menginterpretasikan PIDL

Menerapkan Antarmuka Utama

Antarmuka IPersistFolder

Antarmuka IShellFolder

EnumObjects

CreateViewObject

GetUIObjectOf

BindToObject

GetDisplayNameOf

GetAttributesOf

ParseDisplayName

Antarmuka IEnumIDList

Menerapkan Antarmuka Opsional

IExtractIcon

IContextMenu

IQueryInfo

IDataObject dan IDropTarget

Bekerja Dengan Implementasi Tampilan Folder Shell Default

Saran dan Komentar

Sumber Daya Tambahan: