ArcGIS Engine Developer Guide

VISUAL C++
Outbound interface—This is an interface of methods that a COM object will
fire at various times. For example, the Map coclass will fire an event on the
IActiveViewEvents in response to changes in the map.
Event source—The source COM object will fire events to an outbound interface
when certain actions occur. For example, the Map coclass is a source of
IActiveViewEvents and will fire the IActiveViewEvents::ItemAdded event when a
new layer is added to the map. The source object can have any number of clients,
or event sink objects, listening to events. Also, a source object may have more than
one outbound interface; for example, the Map coclass also fires events on an
IMapEvents interface. An event source will typically declare its outbound interfaces
in IDL with the [source] tag.
Event sink—A COM object that listens to events is said to be a sink for events.
The sink object implements the outbound interface; this is not always advertised
in the type libraries because the sink may listen to events internally. An event sink
typically uses the connection point mechanism to register its interest in the events of
a source object.
Connection point—COM objects that are the source of events typically use the
connection point mechanism to allow sinks to hook up to a source. The connection
point interfaces are the standard COM interfaces IConnectionPointContainer and
IConnectionPoint.
Fire event—When a source object needs to inform all the sinks of a particular
action, the source is said to fire an event. This results in the source iterating all
the sinks and making the same method call on each. For example, when a layer is
added to a map, the Map coclass is said to fire the ItemAdded event. So all the
objects listening to the Map’s outbound IActiveViewEvents interface will be called
on their implementation of the ItemAdded method.
Advise and unadvise events—To begin receiving events, a sink object is said
to advise a source object that it needs to receive events. When events are no
longer required, the sink will unadvise the source.
The ConnectionPoint mechanism
The source object implements the IConnectionPointContainer interface to allow sinks
to query a source for a specific outbound interface. The following steps are
performed to begin listening to an event. ATL implements this with the AtlAdvise
method.
1. The sink will QI the source object’s IConnectionPointContainer and call
FindConnectionPoint to supply an interface ID for outbound interfaces. To be
able to receive events, the sink object must implement this interface.
2. The source may implement many outbound interfaces and will return a pointer
to a specific connection point object implementing IConnectionPoint to represent
one outbound interface.
3. The sink calls IConnectionPoint::Advise, passing a pointer to its own IUnknown
implementation. The source will store this with any other sinks that may be
listening to events. If the call to Advise was successful, the sink will be given
an identifier—a simple unsigned long value called a cookie—to give back to
the source at a later point when it no longer needs to listen to events.
Chapter 4 • Developer environments • 129