Metode IMoniker::BindToObject (objidl.h)

Artikel
03/15/2023

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.

Sintaks

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

Parameter

[in] pbc

Penunjuk ke antarmuka IBindCtx pada objek konteks ikatan, yang digunakan dalam operasi pengikatan ini. Konteks ikatan menyimpan objek yang terikat selama proses pengikatan, berisi parameter yang berlaku untuk semua operasi menggunakan konteks ikatan, dan menyediakan sarana di mana implementasi moniker harus mengambil informasi tentang lingkungannya.

[in] pmkToLeft

Jika moniker adalah bagian dari moniker komposit, arahkan ke moniker di sebelah kiri moniker ini. Parameter ini terutama digunakan oleh pelaksana moniker untuk memungkinkan kerja sama antara berbagai komponen moniker komposit. Klien Moniker harus menggunakan NULL.

[in] riidResult

IID antarmuka yang ingin digunakan klien untuk berkomunikasi dengan objek yang diidentifikasi moniker.

[out] ppvResult

Alamat variabel pointer yang menerima pointer antarmuka yang diminta dalam riid. Setelah berhasil dikembalikan, *ppvResult berisi penunjuk antarmuka yang diminta ke objek yang diidentifikasi moniker. Ketika berhasil, implementasi harus memanggil AddRef pada moniker. Pemanggil bertanggung jawab untuk memanggil Rilis. Jika terjadi kesalahan, *ppvResult harus NULL.

Nilai kembali

Metode ini dapat mengembalikan nilai pengembalian standar E_OUTOFMEMORY dan E_UNEXPECTED, serta nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Operasi pengikatan berhasil.
MK_E_NOOBJECT	Objek yang diidentifikasi oleh moniker ini, atau beberapa objek yang diidentifikasi oleh moniker komposit di mana moniker ini adalah bagian, tidak dapat ditemukan.
MK_E_EXCEEDEDDEADLINE	Operasi pengikatan tidak dapat diselesaikan dalam batas waktu yang ditentukan oleh struktur BIND_OPTS konteks ikat.
MK_E_CONNECTMANUALLY	Operasi pengikatan memerlukan bantuan dari pengguna akhir. Alasan paling umum untuk mengembalikan nilai ini adalah bahwa kata sandi diperlukan atau bahwa floppy perlu dipasang. Ketika nilai ini dikembalikan, ambil moniker yang menyebabkan kesalahan dengan panggilan ke IBindCtx::GetObjectParam dengan kunci "ConnectManually". Anda kemudian dapat memanggil IMoniker::GetDisplayName untuk mendapatkan nama tampilan, menampilkan kotak dialog yang mengomunikasikan informasi yang diinginkan, seperti instruksi untuk memasang floppy atau permintaan kata sandi, lalu mencoba kembali operasi pengikatan.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Objek perantara ditemukan tetapi tidak mendukung antarmuka yang diperlukan untuk menyelesaikan operasi pengikatan. Misalnya, moniker item mengembalikan nilai ini jika kontainernya tidak mendukung antarmuka IOleItemContainer .
STG_E_ACCESSDENIED	Tidak dapat mengakses objek penyimpanan.

Metode ini juga dapat mengembalikan kesalahan yang terkait dengan metode IOleItemContainer::GetObject .

Keterangan

BindToObject mengimplementasikan fungsi utama moniker, yaitu menemukan objek yang diidentifikasi oleh moniker dan mengembalikan pointer ke salah satu antarmukanya.

Catatan untuk Penelepon

Jika Anda menggunakan moniker sebagai koneksi persisten antara dua objek, Anda mengaktifkan koneksi dengan memanggil BindToObject.

Anda biasanya memanggil BindToObject selama proses berikut:

Buat objek konteks ikatan dengan panggilan ke fungsi CreateBindCtx .
Panggil BindToObject menggunakan moniker, mengambil pointer ke antarmuka yang diinginkan pada objek yang diidentifikasi.
Merilis konteks ikatan.
Melalui penunjuk antarmuka yang diperoleh, lakukan operasi yang diinginkan pada objek .
Setelah selesai dengan objek, lepaskan penunjuk antarmuka objek.

Fragmen kode berikut mengilustrasikan langkah-langkah ini.

HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &amp;pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk-&gt;BindToObject(pbc, NULL, IID_ICellRange, &amp;pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc-&gt;Release(); 
pCellRange-&gt;Release();

Anda juga dapat menggunakan fungsi BindMoniker saat Anda hanya berniat satu operasi pengikatan dan tidak perlu mempertahankan objek konteks ikatan. Fungsi pembantu ini merangkum pembuatan konteks ikatan, memanggil BindToObject dan merilis konteks ikatan.

Kontainer COM yang mendukung tautan ke objek menggunakan moniker untuk menemukan dan mendapatkan akses ke objek tertaut tetapi biasanya tidak memanggil BindToObject secara langsung. Sebaliknya, ketika pengguna mengaktifkan tautan dalam kontainer, kontainer tautan biasanya memanggil IOleObject::D oVerb, menggunakan implementasi handler tautan, yang memanggil BindToObject pada moniker yang disimpan di objek tertaut (jika tidak dapat menangani kata kerja).

Catatan untuk Pelaksana

Apa yang dilakukan implementasi Anda tergantung pada apakah Anda mengharapkan moniker Anda memiliki awalan; yaitu, apakah Anda mengharapkan parameter pmkToLeft menjadi NULL atau tidak. Misalnya, moniker item, yang mengidentifikasi objek dalam kontainer, mengharapkan pmkToLeft mengidentifikasi kontainer. Item moniker akibatnya menggunakan pmkToLeft untuk meminta layanan dari kontainer tersebut. Jika Anda mengharapkan moniker Anda memiliki awalan, Anda harus menggunakan parameter pmkToLeft (misalnya, memanggil BindToObject di dalamnya) untuk meminta layanan dari objek yang diidentifikasinya.

Jika Anda mengharapkan moniker Anda tidak memiliki awalan, implementasi BindToObject Anda harus terlebih dahulu memeriksa tabel objek yang sedang berjalan (ROT) untuk melihat apakah objek sudah berjalan. Untuk memperoleh pointer ke ROT, implementasi Anda harus memanggil IBindCtx::GetRunningObjectTable pada parameter pbc . Anda kemudian dapat memanggil metode IRunningObjectTable::GetObject untuk melihat apakah moniker saat ini telah terdaftar di ROT. Jika demikian, Anda dapat segera memanggil QueryInterface untuk mendapatkan penunjuk ke antarmuka yang diminta oleh pemanggil.

Saat implementasi BindToObject Anda mengikat ke beberapa objek, implementasi tersebut harus menggunakan parameter pbc untuk memanggil IBindCtx::RegisterObjectBound untuk menyimpan referensi ke objek terikat dalam konteks ikatan. Ini memastikan bahwa objek terikat tetap berjalan sampai konteks ikatan dirilis, yang dapat menghindari pengeluaran memiliki operasi pengikatan berikutnya memuatnya lagi nanti.

Jika struktur BIND_OPTS konteks ikat menentukan bendera BINDFLAGS_JUSTTESTEXISTENCE, implementasi Anda memiliki opsi untuk mengembalikan NULL di ppvResult (meskipun Anda juga dapat mengabaikan bendera dan melakukan operasi pengikatan lengkap).

Catatan khusus implementasi

Implementasi	Catatan
Anti-moniker	Metode ini tidak diterapkan. Ini mengembalikan E_NOTIMPL.
Moniker kelas	Jika pmkLeft adalah NULL, memanggil CoGetClassObject, menggunakan CLSID, moniker kelas diinisialisasi dengan (di CreateClassMoniker atau melalui MkParseDisplayName) dan CLSCTX dari pbc saat ini (IBindCtx). Jika pmkLeftnon-NULL, panggil pmkLeft-BindToObject> untuk IClassActivator dan memanggil IClassActivator::GetClassObject dengan CLSID yang diinisialisasi dengan dan CLSCTX dan parameter lokal pbc saat ini (IBindCtx).
Moniker file	Ketika pmkToLeftadalah NULL, metode mencari moniker di ROT dan, jika ditemukan, meminta objek yang diambil untuk penunjuk antarmuka yang diminta. Jika moniker tidak ditemukan di ROT, metode memuat objek dari sistem file dan mengambil penunjuk antarmuka yang diminta. Jika pmkLeft bukan NULL, alih-alih menentukan kelas untuk membuat instans dan menginisialisasi dengan konten file yang dimaksud oleh moniker file menggunakan GetClassFile (atau cara lain), panggil pmkLeft-BindToObject> untuk IClassFactory dan IClassActivator, ambil pointer ini di pcf. Jika gagal dengan E_NOINTERFACE, kembalikan MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Jika penunjuk IClassFactory berhasil diambil, panggil pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) untuk mendapatkan instans baru kelas yang akan diinisialisasi dan menginisialisasinya dengan menggunakan IPersistFile atau cara lain yang sesuai sesuai dengan jalur inisialisasi moniker file yang ada.
Moniker komposit generik	Jika pmkToLeftNULL, metode ini mencari moniker di ROT dan, jika ditemukan, meminta objek yang diambil untuk penunjuk antarmuka yang diminta. Jika pmkToLeft bukan NULL, metode secara rekursif memanggil BindToObject pada komponen paling kanan komposit, meneruskan sisa komposit sebagai parameter pmkToLeft untuk panggilan tersebut.
Moniker item	Jika pmkToLeftADALAH NULL, metode ini mengembalikan E_INVALIDARG. Jika tidak, metode memanggil BindToObject pada parameter pmkToLeft , meminta penunjuk antarmuka IOleItemContainer . Metode kemudian memanggil IOleItemContainer::GetObject, meneruskan string yang terkandung dalam moniker, dan mengembalikan penunjuk antarmuka yang diminta.
Moniker OBJREF	Parameter pmkToLeft harus NULL. Karena moniker OBJREF mewakili objek yang sedang berjalan, tidak ada aktivasi yang terjadi. Jika objek yang diwakili tidak lagi berjalan, BindToObject gagal dengan E_UNEXPECTED.
Penunjuk moniker	Metode ini mengkueri penunjuk yang dibungkus untuk antarmuka yang diminta.
Moniker URL	Karena URL Moniker mendukung pengikatan asinkron, nilai pengembalian aktual dari BindToObject-nya dapat bervariasi tergantung pada parameter objek yang ditetapkan dalam konteks ikatan. Untuk informasi selengkapnya, lihat di bawah ini.

Semantik operasi pengikatan untuk moniker URL identik terlepas dari penggunaan sinkron atau asinkron, dan sebagai berikut:

Moniker URL menarik informasi lebih lanjut untuk operasi pengikatan dari konteks ikatan. Misalnya, moniker dapat memperoleh pointer ke antarmuka IBindStatusCallback dan IEnumFORMATETC yang terdaftar dalam konteks ikat. Informasi lebih lanjut dapat mencakup opsi ikatan tambahan yang ditentukan pada konteks ikat melalui IBindCtx::SetBindOptions, seperti parameter dwTickCountDeadline atau nilai grfFlags BIND_MAYBOTHERUSER.
Selanjutnya moniker memeriksa ROT konteks ikatan untuk menentukan apakah objek yang dirujuk sudah berjalan. Moniker dapat memperoleh informasi ini dengan panggilan berikut:
```
IBindCtx::GetRunningObjectTable(&amp;prot)
prot-&gt;IsRunning(this)
```
Jika objek sudah berjalan, moniker mengambil objek yang sedang berjalan dengan panggilan berikut:
```
prot-&gt;GetObject(this, &amp;punk)
```
Kemudian moniker memanggil QueryInterface untuk antarmuka yang diminta.
Jika tidak, moniker meminta klien dengan memanggil IBindStatusCallback::GetBindInfo untuk mendapatkan informasi ikatan tambahan. Moniker kemudian memulai operasi pengikatan dan meneruskan antarmuka IBinding yang dihasilkan kembali ke klien dengan memanggil IBindStatusCallback::OnStartBinding.
Jika pada langkah 1 ditentukan bahwa ini adalah ikatan asinkron, BindToObject mengembalikan MK_S_ASYNCHRONOUS pada titik ini dengan NULL di ppv. Pemanggil akan menerima penunjuk objek aktual selama metode IBindStatusCallback::OnObjectAvailable di beberapa titik nanti. Langkah-langkah berikut kemudian terjadi secara asinkron ke pemanggil, biasanya pada utas eksekusi lain.
Kelas sumber daya yang ditunjuk oleh URL Moniker ditentukan dengan salah satu cara berikut:
- Moniker URL memeriksa jenis media data. Jika jenis media adalah application/x-oleobject, 16 byte pertama dari data aktual (Content-Body) berisi CLSID sumber daya dan data berikutnya akan ditafsirkan oleh kelas itu sendiri. Untuk semua jenis media lainnya, URL Moniker melihat registri sistem untuk kunci HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID. Perhatikan bahwa aplikasi/x-oleobject akan digunakan hingga aplikasi/oleobject disetujui.
- Moniker URL cocok dengan bagian data yang tiba ke pola yang terdaftar dalam registri sistem di bawah HKEY_CLASSES_ROOT\FileTypes.
- Terakhir, jika semuanya gagal, URL Moniker menghubungkan ekstensi sumber daya berikutnya, jika ada, ke CLSID menggunakan HKEY_CLASSES_ROOT\.??? kunci dalam registri sistem, seperti yang dilakukan oleh GetClassFile dan shell.
Setelah menentukan kelas, moniker URL membuat instans menggunakan CoCreateInstance CLSCTX_SERVER meminta antarmuka IUnknown .
Moniker URL selanjutnya memanggil metode QueryInterface dari objek yang baru dibuat untuk antarmuka IPersistMoniker . Jika QueryInterface berhasil, moniker URL memanggil IPersistMoniker::Load passing sendiri (ini) sebagai parameter moniker. Objek biasanya memanggil BindToStorage yang meminta antarmuka penyimpanan yang mereka minati.
Jika tidak, moniker URL memanggil QueryInterface untuk IPersistStream dan, jika berhasil, memanggil IPersistStream::Load, meneruskan objek penunjuk IStream untuk objek stream yang sedang diisi secara asinkron oleh transportasi.
Jika kelas yang dipanggil tidak ditandai dengan kategori CATID_AsyncAware, panggilan ke ISequentialStream::Read atau ISequentialStream::Tulis bahwa data referensi belum tersedia blok hingga data tersedia. Panggilan ini memblokir dalam arti COM tradisional. Perulangan pesan dimasukkan yang memungkinkan pesan tertentu diproses, dan IMessageFilter utas dipanggil dengan tepat.

Jika kelas ditandai dengan kategori CATID_AsyncAware, panggilan ke ISequentialStream::Read atau ISequentialStream::Tulis data referensi yang belum tersedia mengembalikan E_PENDING.
Jika tidak, moniker URL memanggil QueryInterface untuk IPersistFile dan, jika berhasil, menyelesaikan unduhan ke dalam file sementara. Setelah selesai, moniker URL memanggil IPersistFile::Load. File yang dibuat di-cache bersama dengan data lain yang diunduh Internet. Klien harus yakin untuk tidak menghapus file ini.
Ketika objek kembali dari salah satu dari berbagai panggilan Muat yang dijelaskan dalam langkah-langkah sebelumnya, moniker URL memanggil metode IBindStatusCallback::OnObjectAvailable untuk mengembalikan penunjuk antarmuka yang awalnya diminta klien saat klien bernama BindToObject.

Persyaratan

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

Lihat juga

BindMoniker

IMoniker