The CConnectionPoint class defines a special type of interface used to communicate with other OLE objects, called a “connection point.” Unlike normal OLE interfaces, which are used to implement and expose the functionality of an OLE control, a connection point implements an outgoing interface that is able to initiate actions on other objects, such as firing events and change notifications.
A connection consists of two parts: the object calling the interface, called the “source,” and the object implementing the interface, called the “sink.” By exposing a connection point, a source allows sinks to establish connections to itself. Through the connection point mechanism, a source object obtains a pointer to the sink’s implementation of a set of member functions. For example, to fire an event implemented by the sink, the source can call the appropriate method of the sink’s implementation.
By default, a COleControl-derived class implements two connection points: one for events and one for property change notifications. These connections are used, respectively, for event firing and for notifying a sink (for example, the control’s container) when a property value has changed. Support is also provided for OLE controls to implement additional connection points. For each additional connection point implemented in your control class, you must declare a “connection part” that implements the connection point. If you implement one or more connection points, you also need to declare a single “connection map” in your control class.
The following example demonstrates a simple connection map and one connection point for the Sample OLE control, consisting of two fragments of code: the first portion declares the connection map and point; the second implements this map and point. The first fragment is inserted into the declaration of the control class, under the protected section:
// Connection point for ISample interface
BEGIN_CONNECTION_PART(CSampleCtrl, SampleConnPt)
CONNECTION_IID(IID_ISampleSink)
END_CONNECTION_PART(SampleConnPt)
DECLARE_CONNECTION_MAP()
The BEGIN_CONNECTION_PART and END_CONNECTION_PART macros declare an embedded class, XSampleConnPt (derived from CConnectionPoint) that implements this particular connection point. If you want to override any CConnectionPoint member functions, or add member functions of your own, declare them between these two macros. For example, the CONNECTION_IID macro overrides the CConnectionPoint::GetIID member function when placed between these two macros.
The second code fragment is inserted into the implementation file (.CPP) of your control class. This code implements the connection map, which includes the additional connection point, SampleConnPt:
BEGIN_CONNECTION_MAP(CSampleCtrl, COleControl)
CONNECTION_PART(CSampleCtrl, IID_ISampleSink, SampleConnPt)
END_CONNECTION_MAP()
Once these code fragments have been inserted, the Sample OLE control exposes a connection point for the ISampleSink interface.
Typically, connection points support “multicasting”; the ability to broadcast to multiple sinks connected to the same interface. The following code fragment demonstrates how to accomplish multicasting by iterating through each sink on a connection point:
void CSampleCtrl::CallSinkFunc()
{
const CPtrArray* pConnections = m_xSampleConnPt.GetConnections();
ASSERT(pConnections != NULL);
int cConnections = pConnections->GetSize();
ISampleSink* pSampleSink;
for (int i = 0; i < cConnections; i++)
{
pSampleSink = (ISampleSink*)(pConnections->GetAt(i));
ASSERT(pSampleSink != NULL);
pSampleSink->SinkFunc();
}
}
This example retrieves the current set of connections on the SampleConnPt connection point with a call to CConnectionPoint::GetConnections. It then iterates through the connections and calls ISampleSink::SinkFunc on every active connection.
For more information on using CConnectionPoint, see the article Connection Points in Visual C++ Programmer's Guide.
#include <afxctl.h>