CConnectionPoint Class
Defines a special type of interface used to communicate with other OLE objects, called a "connection point."
Syntax
class CConnectionPoint : public CCmdTarget
Members
Public Constructors
| Name | Description |
|---|---|
| CConnectionPoint::CConnectionPoint | Constructs a CConnectionPoint object. |
Public Methods
| Name | Description |
|---|---|
| CConnectionPoint::GetConnections | Retrieves all connection points in a connection map. |
| CConnectionPoint::GetContainer | Retrieves the container of the control that owns the connection map. |
| CConnectionPoint::GetIID | Retrieves the interface ID of a connection point. |
| CConnectionPoint::GetMaxConnections | Retrieves the maximum number of connection points supported by a control. |
| CConnectionPoint::GetNextConnection | Retrieves a pointer to the connection element at pos. |
| CConnectionPoint::GetStartPosition | Starts a map iteration by returning a POSITION value that can be passed to a GetNextConnection call. |
| CConnectionPoint::OnAdvise | Called by the framework when establishing or breaking connections. |
| CConnectionPoint::QuerySinkInterface | Retrieves a pointer to the requested sink interface. |
Remarks
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(CMyClass, 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(CMyClass, CCmdTarget)
CONNECTION_PART(CMyClass, 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", which is 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 CMyClass::CallSinkFunc()
{
POSITION pos = m_xSampleConnPt.GetStartPosition();
ISampleSink *pSampleSink;
while (pos != NULL)
{
pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
if (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.
Inheritance Hierarchy
CConnectionPoint
Requirements
Header: afxdisp.h
CConnectionPoint::CConnectionPoint
Constructs a CConnectionPoint object.
CConnectionPoint();
CConnectionPoint::GetConnections
Call this function to retrieve all active connections for a connection point.
const CPtrArray* GetConnections();
Return Value
A pointer to an array of active connections (sinks). Some of the pointers in the array may be NULL. Each non-NULL pointer in this array can be safely converted to a pointer to the sink interface using a cast operator.
CConnectionPoint::GetContainer
Called by the framework to retrieve the IConnectionPointContainer for the connection point.
virtual LPCONNECTIONPOINTCONTAINER GetContainer();
Return Value
If successful, a pointer to the container; otherwise NULL.
Remarks
This function is typically implemented by the BEGIN_CONNECTION_PART macro.
CConnectionPoint::GetIID
Called by the framework to retrieve the interface ID of a connection point.
virtual REFIID GetIID() = 0;
Return Value
A reference to the connection point's interface ID.
Remarks
Override this function to return the interface ID for this connection point.
CConnectionPoint::GetMaxConnections
Called by the framework to retrieve the maximum number of connections supported by the connection point.
virtual int GetMaxConnections();
Return Value
The maximum number of connections supported by the control, or -1 if no limit.
Remarks
The default implementation returns -1, indicating no limit.
Override this function if you want to limit the number of sinks that can connect to your control.
CConnectionPoint::GetNextConnection
Retrieves a pointer to the connection element at pos.
LPUNKNOWN GetNextConnection(POSITION& pos) const;
Parameters
pos
Specifies a reference to a POSITION value returned by a previous GetNextConnection or GetStartPosition call.
Return Value
A pointer to the connection element specified by pos, or NULL.
Remarks
This function is most useful for iterating through all the elements in the connection map. When iterating, skip any NULLs returned from this function.
Example
void CMyClass::CallSinkFunc()
{
POSITION pos = m_xSampleConnPt.GetStartPosition();
ISampleSink *pSampleSink;
while (pos != NULL)
{
pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
if (pSampleSink != NULL)
{
pSampleSink->SinkFunc();
}
}
}
CConnectionPoint::GetStartPosition
Starts a map iteration by returning a POSITION value that can be passed to a GetNextConnection call.
POSITION GetStartPosition() const;
Return Value
A POSITION value that indicates a starting position for iterating the map; or NULL if the map is empty.
Remarks
The iteration sequence is not predictable; therefore, the "first element in the map" has no special significance.
Example
See the example for CConnectionPoint::GetNextConnection.
CConnectionPoint::OnAdvise
Called by the framework when a connection is being established or broken.
virtual void OnAdvise(BOOL bAdvise);
Parameters
bAdvise
TRUE, if a connection is being established; otherwise FALSE.
Remarks
The default implementation does nothing.
Override this function if you want notification when sinks connect to or disconnect from your connection point.
CConnectionPoint::QuerySinkInterface
Retrieves a pointer to the requested sink interface.
virtual HRESULT QuerySinkInterface(
LPUNKNOWN pUnkSink,
void** ppInterface);
Parameters
pUnkSink
The identifier of the sink interface being requested.
ppInterface
A pointer to the interface pointer identified by pUnkSink. If the object does not support this interface, * ppInterface is set to NULL.
Return Value
A standard HRESULT value.