Antarmuka IMoniker (objidl.h)

Artikel
08/25/2023

Memungkinkan Anda menggunakan objek moniker, yang berisi informasi yang secara unik mengidentifikasi objek COM. Objek yang memiliki penunjuk ke antarmuka IMoniker objek moniker dapat menemukan, mengaktifkan, dan mendapatkan akses ke objek yang diidentifikasi tanpa memiliki informasi spesifik lainnya di mana objek sebenarnya berada dalam sistem terdistribusi.

Monikers digunakan sebagai dasar untuk menautkan dalam COM. Objek tertaut berisi moniker yang mengidentifikasi sumbernya. Ketika pengguna mengaktifkan objek tertaut untuk mengeditnya, moniker terikat; ini memuat sumber tautan ke dalam memori.

Warisan

Antarmuka IMoniker mewarisi dari IPersistStream. IMoniker juga memiliki jenis anggota ini:

Metode

Antarmuka IMoniker memiliki metode ini.


IMoniker::BindToObject Mengikat ke objek yang ditentukan. Proses pengikatan melibatkan menemukan objek , memasukkannya ke dalam status berjalan jika perlu, dan menyediakan pemanggil dengan penunjuk ke antarmuka tertentu pada objek yang diidentifikasi.
IMoniker::BindToStorage Mengikat ke penyimpanan untuk objek yang ditentukan. Tidak seperti metode IMoniker::BindToObject, metode ini tidak mengaktifkan objek yang diidentifikasi oleh moniker.
IMoniker::CommonPrefixWith Membuat moniker baru berdasarkan awalan yang dimiliki moniker ini sama dengan moniker yang ditentukan.
IMoniker::ComposeWith Membuat moniker komposit baru dengan menggabungkan moniker saat ini dengan moniker yang ditentukan.
IMoniker::Enum Mengambil pointer ke enumerator untuk komponen moniker komposit.
IMoniker::GetDisplayName Mengambil nama tampilan untuk moniker.
IMoniker::GetTimeOfLastChange Mengambil waktu di mana objek yang diidentifikasi oleh moniker ini terakhir diubah.
IMoniker::Hash Membuat nilai hash menggunakan status internal moniker.
IMoniker::Inverse Membuat moniker yang merupakan inversi dari moniker ini. Ketika disusun di sebelah kanan moniker ini atau salah satu struktur yang sama, moniker akan menyusun apa-apa.
IMoniker::IsEqual Menentukan apakah moniker ini identik dengan moniker yang ditentukan.
IMoniker::IsRunning Menentukan apakah objek yang diidentifikasi oleh moniker ini saat ini dimuat dan dijalankan.
IMoniker::IsSystemMoniker Menentukan apakah moniker ini adalah salah satu kelas moniker yang disediakan sistem.
IMoniker::P arseDisplayName Mengonversi nama tampilan menjadi moniker.
IMoniker::Reduce Mengurangi moniker ke bentuk yang paling sederhana.
IMoniker::RelativePathTo Membuat moniker relatif antara moniker ini dan moniker yang ditentukan.

Keterangan

Seperti jalur ke file dalam sistem file, moniker berisi informasi yang memungkinkan objek COM ditemukan dan diaktifkan. Monikers dapat mengidentifikasi semua jenis objek COM, dari objek dokumen yang disimpan dalam file ke pilihan dalam objek yang disematkan. COM menyediakan satu set kelas moniker yang memungkinkan Anda membuat objek moniker yang mengidentifikasi objek yang paling umum ditemukan dalam sistem. Misalnya, mungkin ada objek yang mewakili rentang sel dalam spreadsheet yang disematkan dalam dokumen teks yang disimpan dalam file. Dalam sistem terdistribusi, moniker objek ini akan mengidentifikasi lokasi sistem objek, lokasi fisik file pada sistem itu, penyimpanan objek yang disematkan dalam file itu, dan, akhirnya, lokasi rentang sel dalam objek yang disematkan.

Objek moniker mendukung antarmuka IMoniker , yang berasal dari antarmuka IPersistStream dan secara unik mengidentifikasi satu objek dalam sistem. Setelah objek yang menyediakan moniker telah membuat objek moniker, informasi ini tidak dapat diubah dalam objek tersebut. Jika penyedia moniker mengubah informasi, penyedia moniker hanya dapat melakukannya dengan membuat objek moniker baru, yang kemudian akan mengidentifikasi objek yang bersangkutan secara unik.

Monikers memiliki dua kemampuan penting berikut:

Monikers dapat disimpan ke penyimpanan persisten. Ketika moniker dimuat kembali ke dalam memori, moniker masih mengidentifikasi objek yang sama.
Monikers mendukung operasi yang disebut pengikatan, yang merupakan proses menemukan objek yang dinamai oleh moniker, mengaktifkannya (memuatnya ke dalam memori) jika belum aktif, dan mengembalikan pointer ke antarmuka yang diminta pada objek tersebut.

Implementasi Anti-Moniker

Anti-monikers adalah inversi dari implementasi COM dari moniker file, item, dan pointer. Artinya, anti-moniker yang disusun di sebelah kanan moniker file, moniker item, atau moniker pointer tidak menyusun apa-apa.

Jika Anda adalah klien moniker, Anda biasanya tidak perlu menggunakan anti-monikers. Ketika Anda membutuhkan inversi moniker, Anda harus memanggil IMoniker::Inverse. Misalnya, jika Anda memerlukan inversi untuk menghapus bagian terakhir dari moniker komposit, gunakan IMoniker::Enum untuk menghitung potongan moniker dan memanggil Inverse pada bagian paling kanan. Anda tidak boleh menggunakan anti-moniker untuk tujuan ini karena Anda tidak dapat yakin bahwa bagian paling kanan dari komposit menganggap anti-moniker sebagai inversinya.

Satu-satunya situasi di mana Anda harus secara eksplisit menggunakan anti-moniker adalah ketika Anda menulis kelas moniker baru dan Anda tidak memiliki persyaratan khusus untuk membangun invers ke moniker Anda. Dalam situasi itu, Anda dapat mengembalikan anti-monikers dari implementasi Inverse Anda. Dalam implementasi IMoniker::ComposeWith, Anda kemudian harus memusnahkan salah satu moniker Anda untuk setiap anti-moniker yang Anda temui.

Gunakan fungsi CreateAntiMoniker untuk membuat moniker ini.

Implementasi Class Moniker

Moniker kelas adalah moniker yang mewakili kelas objek. Moniker kelas mengikat objek kelas kelas tempat mereka dibuat.

Moniker kelas paling berguna dalam komposisi dengan jenis moniker lainnya, seperti moniker file atau moniker item. Moniker kelas juga dapat disusun di sebelah kanan moniker yang mendukung pengikatan ke antarmuka IClassActivator . Ini memungkinkan IClassActivator untuk menyediakan akses ke objek kelas dan instans kelas.

Untuk menggunakan moniker kelas, Anda harus menggunakan fungsi CreateClassMoniker untuk membuat moniker ini.

Implementasi File Moniker

Moniker file adalah moniker yang mewakili jalur dalam sistem file; moniker file dapat mengidentifikasi objek apa pun yang disimpan dalam filenya sendiri. Untuk mengidentifikasi objek yang terkandung dalam file, Anda dapat menyusun moniker dari kelas lain (misalnya, moniker item) di sebelah kanan moniker file. Namun, moniker di sebelah kiri file moniker dalam komposit harus berupa moniker file lain, anti-moniker, atau moniker kelas. Ini ilegal, misalnya, agar item moniker muncul di sebelah kiri file moniker dalam komposit.

Perhatikan bahwa anti-moniker adalah inversi dari seluruh moniker file, bukan inversi dari komponen jalur yang diwakili moniker; yaitu, ketika Anda membuat anti-moniker di sebelah kanan file moniker, seluruh file moniker dihapus. Jika Anda hanya ingin menghapus komponen paling kanan dari jalur yang diwakili oleh moniker file, Anda harus membuat moniker file terpisah berdasarkan jalur ".." dan kemudian menyusunnya ke akhir moniker file.

Klien moniker (menggunakan moniker untuk mendapatkan penunjuk antarmuka ke objek) biasanya tidak perlu mengetahui kelas moniker; cukup memanggil metode menggunakan penunjuk antarmuka IMoniker .

Penyedia moniker (membagikan moniker yang mengidentifikasi objeknya untuk membuatnya dapat diakses oleh klien moniker) harus menggunakan moniker file jika objek yang mereka identifikasi disimpan dalam file. Jika setiap objek berada dalam filenya sendiri, moniker file adalah satu-satunya jenis yang diperlukan. Jika objek yang diidentifikasi lebih kecil dari file, Anda perlu menggunakan jenis moniker lain (misalnya, moniker item) selain moniker file.

Untuk menggunakan moniker file, Anda harus menggunakan fungsi CreateFileMoniker untuk membuat moniker. Untuk memungkinkan objek Anda dimuat saat moniker file terikat, objek Anda harus mengimplementasikan antarmuka IPersistFile .

Contoh paling umum dari penyedia moniker adalah aplikasi server COM yang mendukung penautan. Jika aplikasi server COM Anda mendukung penautan hanya ke dokumen berbasis file secara keseluruhan, moniker file adalah satu-satunya jenis moniker yang Anda butuhkan. Jika aplikasi server COM Anda mendukung penautan ke objek yang lebih kecil dari dokumen (seperti bagian dokumen atau objek yang disematkan), Anda harus menggunakan moniker item serta moniker file.

Implementasi Moniker Komposit Generik

Moniker komposit generik adalah moniker komposit yang komponennya tidak memiliki pengetahuan khusus satu sama lain.

Komposisi adalah proses menggabungkan dua moniker bersama-sama. Terkadang dua moniker kelas tertentu dapat digabungkan dengan cara khusus; misalnya, moniker file yang mewakili jalur yang tidak lengkap dan moniker file lain yang mewakili jalur relatif dapat digabungkan untuk membentuk moniker file tunggal yang mewakili jalur lengkap. Ini adalah contoh komposisi nongenerik. Komposisi generik, di sisi lain, dapat menghubungkan dua moniker, tidak peduli apa kelas mereka. Karena komposisi nongenerik tergantung pada kelas moniker yang terlibat, itu hanya dapat dilakukan dengan implementasi kelas tertentu dari metode IMoniker::ComposeWith . Anda dapat menentukan jenis komposisi nongenerik baru jika Anda menulis kelas moniker baru. Sebaliknya, komposisi generik dilakukan oleh fungsi CreateGenericComposite .

Klien moniker (menggunakan moniker untuk mendapatkan penunjuk antarmuka ke objek) biasanya tidak perlu mengetahui kelas moniker, atau apakah itu komposit generik atau komposit nongenerik; ini hanya dapat memanggil metode menggunakan penunjuk antarmuka IMoniker .

Penyedia moniker (membagikan moniker yang mengidentifikasi objeknya untuk membuatnya dapat diakses oleh klien moniker) mungkin perlu menyusun dua moniker bersama-sama. (Misalnya, jika Anda menggunakan moniker item untuk mengidentifikasi objek, Anda harus menyusunnya dengan moniker yang mengidentifikasi kontainer objek sebelum Anda membagikannya.) Gunakan metode IMoniker::ComposeWith untuk melakukan ini, memanggil metode pada moniker pertama dan meneruskan moniker kedua sebagai parameter; metode ini dapat menghasilkan komposit generik atau nongenerik.

Satu-satunya waktu Anda harus secara eksplisit membuat moniker komposit generik adalah ketika Anda menulis kelas moniker Anda sendiri. Dalam implementasi IMoniker::ComposeWith, Anda harus mencoba melakukan komposisi nongenerik jika memungkinkan; jika Anda tidak dapat melakukan komposisi nongenerik dan komposisi generik dapat diterima, Anda dapat memanggil fungsi CreateGenericComposite untuk membuat moniker komposit generik.

Implementasi Item Moniker

Moniker item digunakan untuk mengidentifikasi objek dalam kontainer, seperti sebagian dokumen, objek yang disematkan dalam dokumen majemuk, atau rentang sel dalam spreadsheet. Moniker item sering digunakan dalam kombinasi dengan moniker file; moniker file digunakan untuk mengidentifikasi kontainer sementara moniker item digunakan untuk mengidentifikasi item dalam kontainer.

Moniker item berisi string teks; string ini digunakan oleh objek kontainer untuk membedakan item yang terkandung dari yang lain. Objek kontainer harus mengimplementasikan antarmuka IOleItemContainer ; antarmuka ini memungkinkan kode moniker item untuk memperoleh penunjuk ke objek, hanya mengingat string yang mengidentifikasi objek.

Klien moniker (menggunakan moniker untuk mendapatkan penunjuk antarmuka ke objek) biasanya tidak perlu mengetahui kelas moniker; ini hanya memanggil metode menggunakan penunjuk antarmuka IMoniker .

Penyedia moniker (membagikan moniker yang mengidentifikasi objeknya untuk membuatnya dapat diakses oleh klien moniker) harus menggunakan moniker item jika objek yang diidentifikasi terkandung dalam objek lain dan dapat diidentifikasi secara individual menggunakan string. Gunakan jenis moniker lain (misalnya, moniker file) untuk mengidentifikasi objek kontainer.

Untuk menggunakan moniker item, Anda harus menggunakan fungsi CreateItemMoniker untuk membuat moniker. Untuk memungkinkan objek Anda dimuat saat item moniker terikat, kontainer objek Anda harus mengimplementasikan antarmuka IOleItemContainer .

Contoh paling umum dari penyedia moniker adalah aplikasi COM yang mendukung penautan. Jika aplikasi COM Anda mendukung penautan ke objek yang lebih kecil dari dokumen berbasis file, Anda perlu menggunakan moniker item. Untuk aplikasi server yang memungkinkan penautan ke pilihan dalam dokumen, Anda menggunakan moniker item untuk mengidentifikasi objek tersebut. Untuk aplikasi kontainer yang memungkinkan penautan ke objek yang disematkan, Anda menggunakan moniker item untuk mengidentifikasi objek yang disematkan.

Implementasi OBJREF Moniker

Moniker OBJREF mewakili referensi ke instans objek yang berjalan di server di luar proses, baik secara lokal maupun jarak jauh. Moniker mengidentifikasi instans objek dan komputer tempat objek dijalankan.

Moniker OBJREF mirip dalam banyak cara dengan moniker pointer, kecuali bahwa objek yang berjalan di luar proses. Klien dapat memanggil IMoniker::BindToObject pada moniker OBJREF dan menggunakan pointer yang diperolehnya untuk mengakses objek yang sedang berjalan, terlepas dari lokasinya.

Perbedaan penting dari moniker penunjuk adalah bahwa nama tampilan moniker OBJREF dapat disematkan di halaman HTML, dan objek yang berjalan yang diwakili oleh moniker dapat diikat oleh skrip klien, applet, atau kontrol ActiveX.

Penggunaan utama untuk moniker OBJREF adalah untuk mendapatkan akses ke instans objek yang sedang berjalan melalui Internet. Halaman server aktif atau beberapa cara lain untuk menghasilkan konten HTML dinamis menempatkan nama tampilan moniker OBJREF dalam parameter ke applet atau kontrol ActiveX. Kode applet atau kontrol memanggil fungsi CreateObjrefMoniker untuk membuat moniker OBJREF berdasarkan nama tampilan, dan kemudian memanggil IMoniker::BindToObject pada moniker OBJREF yang dihasilkan untuk mendapatkan akses ke instans objek yang sedang berjalan. Halaman server aktif kemudian membuat marshal penunjuk ke objek yang sedang berjalan kembali ke klien halaman.

Implementasi Pointer Moniker

Moniker pointer pada dasarnya membungkus penunjuk antarmuka sehingga terlihat seperti moniker dan dapat diteruskan ke antarmuka yang memerlukan moniker. Mengikat moniker pointer dilakukan dengan memanggil metode QueryInterface pointer.

Instans moniker pointer menolak untuk diserialisasikan; artinya, IPersistStream::Save akan mengembalikan kesalahan. Namun, para moniker ini dapat dijadikan marshal ke proses yang berbeda dalam panggilan RPC; secara internal, sistem marsekal dan membatalkan nama penunjuk dengan menggunakan paradigma standar untuk marshaling penunjuk antarmuka.

Moniker pointer jarang diperlukan. Gunakan moniker pointer hanya jika Anda memerlukan moniker untuk mengidentifikasi objek yang tidak memiliki representasi persisten. Moniker pointer memungkinkan objek tersebut untuk berpartisipasi dalam operasi pengikatan moniker.

Implementasi URL Moniker

Implementasi URL moniker IMoniker ditemukan pada objek moniker URL, yang juga mendukung IUnknown dan antarmuka IAsyncMoniker . Antarmuka IMoniker mewarisi definisinya dari IPersistStream serta IUnknown, dan IPersistStream mewarisi dari IPersist. Oleh karena itu, implementasi IMoniker mencakup dukungan untuk IPersistStream dan IPersist.

Antarmuka IAsyncMoniker hanyalah IUnknown. (Tidak ada metode tambahan.) Ini digunakan untuk memungkinkan klien menentukan apakah moniker mendukung pengikatan asinkron.

Untuk mendapatkan penunjuk ke antarmuka IMoniker pada objek ini, panggil fungsi CreateURLMonikerEx .

Klien moniker (menggunakan moniker untuk mendapatkan penunjuk antarmuka ke objek) biasanya tidak perlu mengetahui kelas moniker yang digunakannya; ini hanya memanggil metode menggunakan penunjuk antarmuka IMoniker .

Penyedia moniker (membagikan moniker yang mengidentifikasi objeknya untuk membuatnya dapat diakses oleh klien moniker) harus menggunakan moniker item jika objek yang diidentifikasi terkandung dalam objek lain dan dapat diidentifikasi secara individual menggunakan string. Ini juga perlu menggunakan jenis moniker lain (misalnya, moniker file) untuk mengidentifikasi objek kontainer.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	objidl.h