Peta koneksi

Kontrol OLE dapat mengekspos antarmuka ke aplikasi lain. Antarmuka ini hanya mengizinkan akses dari kontainer ke kontrol tersebut. Jika kontrol OLE ingin mengakses antarmuka eksternal objek OLE lainnya, titik koneksi harus dibuat. Titik koneksi ini memungkinkan akses keluar kontrol ke peta pengiriman eksternal, seperti peta peristiwa atau fungsi pemberitahuan.

Pustaka Kelas Microsoft Foundation menawarkan model pemrograman yang mendukung titik koneksi. Dalam model ini, "peta koneksi" digunakan untuk menunjuk antarmuka atau titik koneksi untuk kontrol OLE. Peta koneksi berisi satu makro untuk setiap titik koneksi. Untuk informasi selengkapnya tentang peta koneksi, lihat CConnectionPoint kelas .

Biasanya, kontrol hanya mendukung dua titik koneksi: satu untuk peristiwa dan satu untuk pemberitahuan properti. Ini diimplementasikan oleh COleControl kelas dasar dan tidak memerlukan pekerjaan tambahan oleh penulis kontrol. Titik koneksi lain yang ingin Anda terapkan di kelas Anda harus ditambahkan secara manual. Untuk mendukung peta koneksi dan titik, MFC menyediakan makro berikut:

Deklarasi dan demarkasi Peta Koneksi

Nama	Deskripsi
BEGIN_CONNECTION_PART	Menyatakan kelas tersemat yang mengimplementasikan titik koneksi tambahan (harus digunakan dalam deklarasi kelas).
END_CONNECTION_PART	Mengakhiri deklarasi titik koneksi (harus digunakan dalam deklarasi kelas).
CONNECTION_IID	Menentukan ID antarmuka titik koneksi kontrol.
DECLARE_CONNECTION_MAP	Menyatakan bahwa peta koneksi akan digunakan dalam kelas (harus digunakan dalam deklarasi kelas).
BEGIN_CONNECTION_MAP	Memulai definisi peta koneksi (harus digunakan dalam implementasi kelas).
END_CONNECTION_MAP	Mengakhiri definisi peta koneksi (harus digunakan dalam implementasi kelas).
CONNECTION_PART	Menentukan titik koneksi dalam peta koneksi kontrol.

Fungsi berikut membantu sink dalam membangun dan memutuskan koneksi menggunakan titik koneksi:

Inisialisasi/penghentian titik koneksi

Nama	Deskripsi
AfxConnectionAdvise	Membuat koneksi antara sumber dan sink.
AfxConnectionUnadvise	Memutuskan koneksi antara sumber dan sink.

BEGIN_CONNECTION_PART

BEGIN_CONNECTION_PART Gunakan makro untuk memulai definisi titik koneksi tambahan di luar titik koneksi pemberitahuan peristiwa dan properti.

BEGIN_CONNECTION_PART(theClass, localClass)

Parameter

theClass Menentukan nama kelas kontrol yang titik koneksinya ini.

localClass Menentukan nama kelas lokal yang mengimplementasikan titik koneksi.

Keterangan

Dalam file deklarasi (.h) yang menentukan fungsi anggota untuk kelas Anda, mulai titik koneksi dengan BEGIN_CONNECTION_PART makro. Kemudian tambahkan CONNECTION_IID makro dan fungsi anggota lain yang ingin Anda terapkan. Terakhir, selesaikan peta titik koneksi dengan END_CONNECTION_PART makro.

Persyaratan

Header afxdisp.h

END_CONNECTION_PART

Mengakhiri deklarasi titik koneksi Anda.

END_CONNECTION_PART(localClass)

Parameter

localClass
Menentukan nama kelas lokal yang mengimplementasikan titik koneksi.

Persyaratan

Header afxdisp.h

CONNECTION_IID

Gunakan antara BEGIN_CONNECTION_PART makro dan END_CONNECTION_PART untuk menentukan ID antarmuka untuk titik koneksi yang didukung oleh kontrol OLE Anda.

CONNECTION_IID(iid)

Parameter

iid
ID antarmuka antarmuka yang dipanggil oleh titik koneksi.

Keterangan

Argumen iid adalah ID antarmuka yang digunakan untuk mengidentifikasi antarmuka yang dipanggil titik koneksi pada sink yang terhubung. Contohnya:

CONNECTION_IID(IID_ISampleSink)

Menentukan titik koneksi yang memanggil ISinkInterface antarmuka.

Persyaratan

Header afxdisp.h

DECLARE_CONNECTION_MAP

Setiap COleControlkelas turunan dalam program Anda dapat menyediakan peta koneksi untuk menentukan titik koneksi tambahan yang didukung kontrol Anda.

DECLARE_CONNECTION_MAP()

Keterangan

Jika kontrol Anda mendukung titik tambahan, gunakan DECLARE_CONNECTION_MAP makro di akhir deklarasi kelas Anda. Kemudian, dalam file .cpp yang menentukan fungsi anggota untuk kelas, gunakan BEGIN_CONNECTION_MAP makro, CONNECTION_PART makro untuk setiap titik koneksi kontrol, dan END_CONNECTION_MAP makro untuk mendeklarasikan akhir peta koneksi.

Persyaratan

Header afxdisp.h

BEGIN_CONNECTION_MAP

Setiap COleControlkelas turunan dalam program Anda dapat menyediakan peta koneksi untuk menentukan titik koneksi yang akan didukung kontrol Anda.

BEGIN_CONNECTION_MAP(theClass, theBase)

Parameter

theClass
Menentukan nama kelas kontrol yang peta koneksinya.

theBase
Menentukan nama kelas theClassdasar .

Keterangan

Dalam file implementasi (.CPP) yang menentukan fungsi anggota untuk kelas Anda, mulai peta koneksi dengan BEGIN_CONNECTION_MAP makro, lalu tambahkan entri makro untuk setiap titik koneksi Anda menggunakan CONNECTION_PART makro. Terakhir, selesaikan peta koneksi dengan END_CONNECTION_MAP makro.

Persyaratan

Header afxdisp.h

END_CONNECTION_MAP

Mengakhiri definisi peta koneksi Anda.

END_CONNECTION_MAP()

Persyaratan

Header afxdisp.h

CONNECTION_PART

Memetakan titik koneksi untuk kontrol OLE Anda ke ID antarmuka tertentu.

CONNECTION_PART(theClass, iid, localClass)

Parameter

theClass
Menentukan nama kelas kontrol yang titik koneksinya ini.

iid
ID antarmuka antarmuka yang dipanggil oleh titik koneksi.

localClass
Menentukan nama kelas lokal yang mengimplementasikan titik koneksi.

Keterangan

Contohnya:

BEGIN_CONNECTION_MAP(CMyClass, CCmdTarget)
    CONNECTION_PART(CMyClass, IID_ISampleSink, SampleConnPt)
END_CONNECTION_MAP()

mengimplementasikan peta koneksi, dengan titik koneksi, yang memanggil IID_ISinkInterface antarmuka.

Persyaratan

Header afxdisp.h

AfxConnectionAdvise

Panggil fungsi ini untuk membuat koneksi antara sumber, yang ditentukan oleh pUnkSrc, dan sink, yang ditentukan oleh pUnkSink.

BOOL AFXAPI AfxConnectionAdvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD FAR* pdwCookie);

Parameter

pUnkSrc
Penunjuk ke objek yang memanggil antarmuka.

pUnkSink
Penunjuk ke objek yang mengimplementasikan antarmuka.

iid
ID antarmuka koneksi.

bRefCount
Untuk koneksi di luar proses, parameter ini harus TRUE, dan menunjukkan bahwa membuat koneksi harus menyebabkan jumlah pUnkSink referensi bertambah.

Untuk koneksi dalam proses, TRUE menunjukkan bahwa membuat koneksi harus menyebabkan jumlah pUnkSink referensi bertambah. FALSE menunjukkan bahwa jumlah referensi tidak boleh bertambah.

Peringatan: Secara umum, tidak dapat diprediksi koneksi mana yang sedang dalam proses dan koneksi mana yang di luar proses, sehingga disarankan untuk selalu mengatur parameter ini ke TRUE.

pdwCookie
Penunjuk ke DWORD tempat pengidentifikasi koneksi dikembalikan. Nilai ini harus diteruskan sebagai dwCookie parameter ke AfxConnectionUnadvise saat memutuskan koneksi.

Tampilkan Nilai

Bukan nol jika koneksi dibuat; jika tidak, 0.

Contoh

//CMySink is a CCmdTarget-derived class supporting automation.
//Instantiate the sink class.
CMySink mysink;

//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Establish a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a cookie identifying the connection, and is needed
//to terminate this connection.
AfxConnectionAdvise(pUnkSrc, IID_ISampleSink, pUnkSink, TRUE, &dwCookie);

Persyaratan

Header: afxctl.h

AfxConnectionUnadvise

Panggil fungsi ini untuk memutuskan koneksi antara sumber, yang ditentukan oleh pUnkSrc, dan sink, yang ditentukan oleh pUnkSink.

BOOL AFXAPI AfxConnectionUnadvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD dwCookie);

Parameter

pUnkSrc
Penunjuk ke objek yang memanggil antarmuka.

pUnkSink
Penunjuk ke objek yang mengimplementasikan antarmuka.

iid
ID antarmuka antarmuka titik koneksi.

bRefCount
Untuk koneksi di luar proses, parameter ini harus TRUE, dan menunjukkan bahwa membuat koneksi harus menyebabkan jumlah pUnkSink referensi dikurangi.

Untuk koneksi dalam proses, TRUE menunjukkan bahwa membuat koneksi harus menyebabkan jumlah pUnkSink referensi dikurangi. FALSE menunjukkan bahwa jumlah referensi tidak boleh direkrementasikan.

Peringatan: Secara umum, tidak dapat diprediksi koneksi mana yang sedang dalam proses dan koneksi mana yang di luar proses, sehingga disarankan untuk selalu mengatur parameter ini ke TRUE.

dwCookie
Pengidentifikasi koneksi dikembalikan oleh AfxConnectionAdvise.

Nilai hasil

Bukan nol jika koneksi terputus; jika tidak, 0.

Contoh

//mysink is a CCmdTarget-derived class supporting automation.
//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Terminate a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a value obtained through AfxConnectionAdvise().
AfxConnectionUnadvise(pUnkSrc, IID_ISampleSink, pUnkSink, TRUE, dwCookie);

Persyaratan

Header: afxctl.h

Lihat juga

Makro dan Global