Bagikan melalui

Menerapkan Objek COM Halaman Properti

  • Artikel

Ekstensi lembar properti adalah objek COM yang diimplementasikan sebagai server in-proc. Ekstensi lembar properti harus mengimplementasikan antarmuka IShellExtInit dan IShellPropSheetExt. Ekstensi lembar properti dibuat saat pengguna menampilkan lembar properti untuk objek kelas tempat ekstensi lembar properti telah didaftarkan di penentu tampilan kelas.

Menerapkan IShellExtInit

Setelah objek COM ekstensi lembar properti dibuat, metode IShellExtInit::Initialize dipanggil. IShellExtInit::Initialize menyediakan ekstensi lembar properti dengan objek IDataObject yang berisi data yang berkaitan dengan objek direktori yang diterapkan lembar properti.

IDataObject berisi data dalam format CFSTR_DSOBJECTNAMES. Format data CFSTR_DSOBJECTNAMES adalah HGLOBAL yang berisi struktur DSOBJECTNAMES. Struktur DSOBJECTNAMES berisi data objek direktori yang diterapkan ekstensi lembar properti.

IDataObject juga berisi data dalam format CFSTR_DS_DISPLAY_SPEC_OPTIONS. Format data CFSTR_DS_DISPLAY_SPEC_OPTIONS adalah HGLOBAL yang berisi struktur DSDISPLAYSPECOPTIONS. DSDISPLAYSPECOPTIONS berisi data konfigurasi untuk digunakan oleh ekstensi.

Jika ada nilai selain S_OK yang dikembalikan dari IShellExtInit::Initialize, lembar properti tidak ditampilkan.

Parameter pidlFolder dan hkeyProgID dari metode IShellExtInit::Initialize tidak digunakan.

Penunjuk IDataObject dapat disimpan oleh ekstensi dengan meningkatkan jumlah referensi IDataObject. Antarmuka ini harus dirilis ketika tidak lagi diperlukan.

Menerapkan IShellPropSheetExt

Setelah IShellExtInit::Initialize mengembalikan, metode IShellPropSheetExt::AddPages dipanggil. Ekstensi lembar properti harus menambahkan halaman atau halaman selama metode ini. Halaman properti dibuat dengan mengisi struktur PROPSHEETPAGE lalu meneruskan struktur ini ke fungsi CreatePropertySheetPage. Halaman properti kemudian ditambahkan ke lembar properti dengan memanggil fungsi panggilan balik yang diteruskan ke IShellPropSheetExt::AddPages dalam parameter lpfnAddPage .

Jika ada nilai selain S_OK yang dikembalikan dari IShellPropSheetExt::AddPages, lembar properti tidak ditampilkan.

Jika ekstensi lembar properti tidak diperlukan untuk menambahkan halaman apa pun ke lembar properti, itu tidak boleh memanggil fungsi panggilan balik yang diteruskan ke IShellPropSheetExt::AddPages di parameter lpfnAddPage .

Metode IShellPropSheetExt::ReplacePage tidak digunakan.

Meneruskan Objek Ekstensi ke Halaman Properti

Objek ekstensi lembar properti independen dari halaman properti. Dalam banyak kasus, diinginkan untuk dapat menggunakan objek ekstensi, atau beberapa objek lain, dari halaman properti. Untuk melakukan ini, atur anggota lParam struktur PROPSHEETPAGE ke penunjuk objek. Halaman properti kemudian dapat mengambil nilai ini saat memproses pesan WM_INITDIALOG. Untuk halaman properti, parameter lParam dari pesan WM_INITDIALOG adalah penunjuk ke struktur PROPSHEETPAGE . Ambil penunjuk objek dengan mentransmisikan lParam pesan WM_INITDIALOG ke pointer PROPSHEETPAGE lalu ambil anggota lParam dari struktur PROPSHEETPAGE .

Contoh kode C++ berikut menunjukkan cara meneruskan objek ke halaman properti.

case WM_INITDIALOG:
    {
        LPPROPSHEETPAGE pPage = (LPPROPSHEETPAGE)lParam;

        if(NULL != pPage)
        {
            CPropSheetExt *pPropSheetExt;
            pPropSheetExt = (CPropSheetExt*)pPage->lParam;

            if(pPropSheetExt)
            {
                return pPropSheetExt>OnInitDialog(wParam, lParam);
            }
        }
    }
    break;

Ketahuilah bahwa setelah IShellPropSheetExt::AddPages dipanggil, lembar properti akan merilis objek ekstensi lembar properti dan tidak pernah menggunakannya lagi. Ini berarti bahwa objek ekstensi akan dihapus sebelum halaman properti ditampilkan. Ketika halaman mencoba mengakses penunjuk objek, memori akan dibebaskan dan penunjuk tidak akan valid. Untuk memperbaiki ini, tambahkan jumlah referensi untuk objek ekstensi saat halaman ditambahkan lalu lepaskan objek saat dialog halaman properti dihancurkan. Ini membuat masalah lain karena kotak dialog halaman properti tidak dibuat sampai pertama kali halaman ditampilkan. Jika pengguna tidak pernah memilih halaman ekstensi, halaman tidak pernah dibuat dan dihancurkan. Ini menghasilkan objek ekstensi tidak pernah dirilis, sehingga terjadi kebocoran memori. Untuk menghindari hal ini, terapkan fungsi panggilan balik halaman properti. Untuk melakukan ini, tambahkan bendera PSP_USECALLBACK ke anggota dwFlags dari struktur PROPSHEETPAGE dan atur anggota pfnCallback dari struktur PROPSHEETPAGE ke alamat fungsi PropSheetPageProc yang diimplementasikan. Ketika fungsi PropSheetPageProc menerima pemberitahuan PSPCB_RELEASE, parameter ppsp PropSheetPageProc berisi penunjuk ke struktur PROPSHEETPAGE. Anggota lParam dari struktur PROPSHEETPAGE berisi pointer ekstensi yang dapat digunakan untuk melepaskan objek.

Contoh kode C++ berikut menunjukkan cara merilis objek ekstensi.

UINT CALLBACK CPropSheetExt::PageCallbackProc(  HWND hWnd,
                                                UINT uMsg,
                                                LPPROPSHEETPAGE ppsp)
{
    switch(uMsg)
    {
    case PSPCB_CREATE:
        // Must return TRUE to enable the page to be created.
        return TRUE;

    case PSPCB_RELEASE:
        {
            /*
            Release the object. This is called even if the page dialog box was 
            never actually created.
            */
            CPropSheetExt *pPropSheetExt = (CPropSheetExt*)ppsp->lParam;

            if(pPropSheetExt)
            {
                pPropSheetExt->Release();
            }
        }
        break;
    }

    return FALSE;
}

Bekerja Dengan Objek Pemberitahuan

Karena halaman ekstensi lembar properti ditampilkan dalam lembar properti yang dibuat oleh komponen yang tidak diketahui oleh ekstensi, perlu menggunakan "manajer" untuk menangani transfer data antara halaman ekstensi dan lembar properti. "Manajer" ini disebut objek pemberitahuan. Objek pemberitahuan beroperasi sebagai moderator antara halaman individual dan lembar properti.

Ketika objek ekstensi lembar properti diinisialisasi, ekstensi harus membuat objek pemberitahuan dengan memanggil ADsPropCreateNotifyObj, melewati IDataObject yang diperoleh dari IShellExtInit::Initialize dan nama objek direktori. Tidak perlu menaikkan jumlah referensi antarmuka IDataObject , karena objek pemberitahuan yang dibuat oleh fungsi ADsPropCreateNotifyObj akan melakukan ini. Handel objek pemberitahuan yang disediakan oleh ADsPropCreateNotifyObj harus disimpan untuk digunakan nanti. ADsPropCreateNotifyObj dapat dipanggil selama IShellExtInit::Initialize atau IShellPropSheetExt::AddPages. Saat ekstensi lembar properti dimatikan, ekstensi harus mengirim pesan WM_ADSPROP_NOTIFY_EXIT ke objek pemberitahuan. Ini menyebabkan objek pemberitahuan menghancurkan dirinya sendiri. Ini paling baik dilakukan ketika fungsi PropSheetPageProc menerima pemberitahuan PSPCB_RELEASE .

Ekstensi lembar properti dapat memperoleh data selain yang disediakan oleh format clipboard CFSTR_DSOBJECTNAMES dengan memanggil ADsPropGetInitInfo. Salah satu keuntungan menggunakan ADsPropGetInitInfo adalah menyediakan objek IDirectoryObject yang digunakan untuk bekerja secara terprogram dengan objek direktori.

Catatan

Tidak seperti kebanyakan metode dan fungsi COM, ADsPropGetInitInfo tidak menaikkan jumlah referensi untuk objek IDirectoryObject. IDirectoryObject tidak boleh dirilis kecuali jumlah referensi bertambah secara manual terlebih dahulu.

 

Ketika halaman properti pertama kali dibuat, ekstensi harus mendaftarkan halaman dengan objek pemberitahuan dengan memanggil ADsPropSetHwnd dengan handel jendela halaman.

ADsPropCheckIfWritable adalah fungsi utilitas yang dapat digunakan ekstensi lembar properti untuk menentukan apakah properti dapat ditulis.

Lain-lain

Handel halaman properti diteruskan ke prosedur kotak dialog halaman. Lembar properti adalah induk langsung halaman properti, sehingga handel lembar properti dapat diperoleh dengan memanggil fungsi GetParent dengan handel halaman properti.

Ketika konten halaman ekstensi berubah, ekstensi harus menggunakan makro PropSheet_Changed untuk memberi tahu lembar properti perubahan. Lembar properti kemudian akan mengaktifkan tombol Terapkan.

Lembar Properti Beberapa Pilihan

Dengan Windows Server 2003 dan sistem operasi yang lebih baru, snap-in MMC administratif Direktori Aktif mendukung ekstensi lembar properti untuk beberapa objek direktori. Lembar properti ini ditampilkan ketika properti ditampilkan untuk lebih dari satu item pada satu waktu. Perbedaan utama antara ekstensi lembar properti pilihan tunggal dan ekstensi lembar properti beberapa pilihan adalah bahwa struktur DSOBJECTNAMES yang disediakan oleh format clipboard CFSTR_DSOBJECTNAMES di IShellExtInit::Initialize akan berisi lebih dari satu struktur DSOBJECT.

Saat objek pemberitahuan dibuat, ekstensi lembar properti multi-pilihan harus meneruskan nama unik yang disediakan oleh snap-in daripada nama yang dibuat oleh ekstensi. Untuk mendapatkan nama unik, minta format clipboard CFSTR_DS_MULTISELECTPROPPAGE dari IDataObject yang diperoleh dari IShellExtInit::Initialize. Data ini adalah HGLOBAL yang berisi string Unicode null-terminated yang merupakan nama unik. Nama unik ini kemudian diteruskan ke fungsi ADsPropCreateNotifyObj untuk membuat objek pemberitahuan. Fungsi contoh CreateADsNotificationObject dalam Contoh Kode untuk Implementasi Objek COM Lembar Properti menunjukkan cara melakukan ini dengan benar, serta kompatibel dengan versi snap-in sebelumnya yang tidak mendukung lembar properti multi-pilihan.

Untuk lembar properti beberapa pilihan, sistem hanya mengikat ke objek pertama dalam array DSOBJECT. Karena itu, ADsPropGetInitInfo hanya menyediakan atribut IDirectoryObject dan write-able untuk objek pertama dalam array. Objek lain dalam array tidak terikat.

Ekstensi lembar properti beberapa pilihan terdaftar di bawah atribut adminMultiselectPropertyPages.

Baru dengan Windows Server 2003

Fitur berikut baru dengan Windows Server 2003.

Jika halaman properti mengalami kesalahan, ADsPropSendErrorMessage dapat dipanggil dengan data kesalahan yang sesuai. ADsPropSendErrorMessage akan menyimpan semua pesan kesalahan dalam antrean. Pesan-pesan ini akan ditampilkan lain kali ADsPropShowErrorDialog dipanggil. Saat ADsPropShowErrorDialog kembali, pesan yang diantrekan akan dihapus.

Windows Server 2003 memperkenalkan fungsi ADsPropSetHwndWithTitle. Fungsi ini mirip dengan ADsPropSetHwnd, tetapi menyertakan judul halaman. Ini memungkinkan kotak dialog kesalahan yang ditampilkan oleh ADsPropShowErrorDialog untuk memberikan data yang lebih berguna kepada pengguna. Jika ekstensi lembar properti menggunakan fungsi ADsPropShowErrorDialog , ekstensi harus menggunakan ADsPropSetHwndWithTitle daripada ADsPropSetHwnd.

Contoh Kode untuk Implementasi Objek COM Lembar Properti