CConnectionPoint Class

Artigo
04/28/2015

Defines a special type of interface used to communicate with other OLE objects, called a "connection point."

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

CObject

CCmdTarget

CConnectionPoint

Requirements

Header: afxdisp.h

Compartilhar via