Connection Maps
The latest version of this topic can be found at Connection Maps.
OLE controls are able to expose interfaces to other applications. These interfaces only allow access from a container into that control. If an OLE control wants to access external interfaces of other OLE objects, a connection point must be established. This connection point allows a control outgoing access to external dispatch maps, such as event maps or notification functions.
The Microsoft Foundation Class Library offers a programming model that supports connection points. In this model, "connection maps" are used to designate interfaces or connection points for the OLE control. Connection maps contain one macro for each connection point. For more information on connection maps, see the CConnectionPoint class.
Typically, a control will support just two connection points: one for events and one for property notifications. These are implemented by the COleControl base class and require no additional work by the control writer. Any additional connection points you want to implement in your class must be added manually. To support connection maps and points, MFC provides the following macros:
Connection Map Declaration and Demarcation
| BEGIN_CONNECTION_PART | Declares an embedded class that implements an additional connection point (must be used in the class declaration). |
| END_CONNECTION_PART | Ends the declaration of a connection point (must be used in the class declaration). |
| CONNECTION_IID | Specifies the interface ID of the control's connection point. |
| DECLARE_CONNECTION_MAP | Declares that a connection map will be used in a class (must be used in the class declaration). |
| BEGIN_CONNECTION_MAP | Begins the definition of a connection map (must be used in the class implementation). |
| END_CONNECTION_MAP | Ends the definition of a connection map (must be used in the class implementation). |
| CONNECTION_PART | Specifies a connection point in the control's connection map. |
The following functions assist a sink in establishing and disconnecting a connection using connection points:
Initialization/Termination of Connection Points
| AfxConnectionAdvise | Establishes a connection between a source and a sink. |
| AfxConnectionUnadvise | Breaks a connection between a source and a sink. |
BEGIN_CONNECTION_PART
Use the BEGIN_CONNECTION_PART macro to begin the definition of additional connection points beyond the event and property notification connection points.
BEGIN_CONNECTION_PART
(theClass, localClass)
Parameters
theClass
Specifies the name of the control class whose connection point this is.
localClass
Specifies the name of the local class that implements the connection point.
Remarks
In the declaration (.h) file that defines the member functions for your class, start the connection point with the BEGIN_CONNECTION_PART macro, then add the CONNECTION_IID macro and any other member functions you wish to implement, and complete the connection point map with the END_CONNECTION_PART macro.
END_CONNECTION_PART
Ends the declaration of your connection point.
END_CONNECTION_PART
(localClass)
Parameters
localClass
Specifies the name of the local class that implements the connection point.
CONNECTION_IID
Use between the BEGIN_CONNECTION_PART and END_CONNECTION_PART macros to define an interface ID for a connection point supported by your OLE control.
CONNECTION_IID
(iid)
Parameters
iid
The interface ID of the interface called by the connection point.
Remarks
The iid argument is an interface ID used to identify the interface that the connection point will call on its connected sinks. For example:
CONNECTION_IID(IID_ISampleSink)
specifies a connection point that calls the ISinkInterface interface.
DECLARE_CONNECTION_MAP
Each COleControl-derived class in your program can provide a connection map to specify additional connection points that your control supports.
DECLARE_CONNECTION_MAP
()
Remarks
If your control supports additional points, use the DECLARE_CONNECTION_MAP macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_CONNECTION_MAP macro, CONNECTION_PART macros for each of the control's connection points, and the END_CONNECTION_MAP macro to declare the end of the connection map.
BEGIN_CONNECTION_MAP
Each COleControl-derived class in your program can provide a connection map to specify connection points that your control will support.
BEGIN_CONNECTION_MAP
(theClass, theBase)
Parameters
theClass
Specifies the name of the control class whose connection map this is.
theBase
Specifies the name of the base class of theClass.
Remarks
In the implementation (.CPP) file that defines the member functions for your class, start the connection map with the BEGIN_CONNECTION_MAP macro, then add macro entries for each of your connection points using the CONNECTION_PART macro. Finally, complete the connection map with the END_CONNECTION_MAP macro.
END_CONNECTION_MAP
Ends the definition of your connection map.
END_CONNECTION_MAP
()
CONNECTION_PART
Maps a connection point for your OLE control to a specific interface ID.
CONNECTION_PART
(theClass, iid, localClass)
Parameters
theClass
Specifies the name of the control class whose connection point this is.
iid
The interface ID of the interface called by the connection point.
localClass
Specifies the name of the local class that implements the connection point.
Remarks
For example:
BEGIN_CONNECTION_MAP(CMyClass, CCmdTarget)
CONNECTION_PART(CMyClass, IID_ISampleSink, SampleConnPt)
END_CONNECTION_MAP()
implements a connection map, with a connection point, that calls the IID_ISinkInterface interface .
AfxConnectionAdvise
Call this function to establish a connection between a source, specified by pUnkSrc, and a sink, specified by pUnkSink.
BOOL AFXAPI AfxConnectionAdvise(
LPUNKNOWN pUnkSrc,
REFIID iid,
LPUNKNOWN pUnkSink,
BOOL bRefCount,
DWORD FAR* pdwCookie);
Parameters
pUnkSrc
A pointer to the object that calls the interface.
pUnkSink
A pointer to the object that implements the interface.
iid
The interface ID of the connection.
bRefCount
TRUE indicates that creating the connection should cause the reference count of pUnkSink to be incremented. FALSE indicates that the reference count should not be incremented.
pdwCookie
A pointer to a DWORD where a connection identifier is returned. This value should be passed as the dwCookie parameter to AfxConnectionUnadvise when disconnecting the connection.
Return Value
Nonzero if a connection was established; otherwise 0.
Example
//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, FALSE, &dwCookie);
AfxConnectionUnadvise
Call this function to disconnect a connection between a source, specified by pUnkSrc, and a sink, specified by pUnkSink.
BOOL AFXAPI AfxConnectionUnadvise(
LPUNKNOWN pUnkSrc,
REFIID iid,
LPUNKNOWN pUnkSink,
BOOL bRefCount,
DWORD dwCookie);
Parameters
pUnkSrc
A pointer to the object that calls the interface.
pUnkSink
A pointer to the object that implements the interface.
iid
The interface ID of the connection point interface.
bRefCount
TRUE indicates that disconnecting the connection should cause the reference count of pUnkSink to be decremented. FALSE indicates that the reference count should not be decremented.
dwCookie
The connection identifier returned by AfxConnectionAdvise.
Return Value
Nonzero if a connection was disconnected; otherwise 0.
Example
//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, FALSE, dwCookie);