COM Events
This topic provides an overview of connection points and introduces the event-related terminology commonly used to describe COM events.
Connection points establish two-way communications between a client and a server in COM. With this mechanism, a COM server can call back to a client when some event has occurred. For example, a server (such as Microsoft Internet Explorer) can raise an event to report a change (such as a title change) to its client program. The client creates an internal COM object called an event sink to prepare for incoming notifications. On receiving the notification, the client can perform the actions associated with the event.
An event sink provides an interface to expose event-related methods to the server. Servers raise events by calling these event-related methods. The client implements the event sink interface as a normal COM interface. The server declares the interface as an outgoing interface; the author of the COM server applies the source attribute to the interface in the type library of the COM server. The server uses definitions from the event sink interface to identify the sink and invoke methods.
A COM client that implements the event sink interface is often called the event sink, or simply the sink. In the following illustration, the sink implements the ISinkEvents interface. The server that raises the event is called the source.
Connection point event model
.gif "COM events")
After the event sink interface is established, the sink must be connected (wired) to the source. The connection point mechanism uses the following protocol to wire together a sink and a source:
The sink queries a server object for the IConnectionPointContainer interface. If the object supports connection points, it returns a pointer.
Using methods on the container object, the sink locates the IConnectionPoint interface representing a specific connection point. Since a server can support multiple outgoing interfaces, a client must match its sink to the interface identifier (IID) of a particular connection point interface.
Having obtained the correct connection point object, the sink calls IConnectionPoint::Advise to register its sink interface pointer. The server (source) holds the connection (and raises events to it) until the client breaks the connection by calling IConnectionPoint::Unadvise.
Visual Basic hides most details of connection points; however, you must include a WithEvents directive in the client's declaration of the server. In C++, client code must query for and call methods on IConnectionPointContainer and IConnectionPoint. The server implements both interfaces.
See Also
Tasks
How to: Raise Events Handled by a COM Sink
How to: Handle Events Raised by a COM Source