Chapter 9. Connection Points

A Review of Connection Points

An object implements one or more interfaces to expose its functionality. The term connection points refers to a logically inverse mechanism that allows an object to expose its capability to call one or more specific interfaces.

Another perspective is that QueryInterface allows a client to retrieve from an object a pointer to an interface that the object implements. Connection points allow a client to give an object a pointer to an interface that the client implements. In the first case, the client uses the retrieved interface pointer to call methods provided by the object. In the second case, the object uses the provided interface pointer to call methods provided by the client.

A slightly closer inspection of the two mechanisms reveals that QueryInterface allows a client to retrieve from an object only interfaces that the client knows how to call. Connection points allow a client to provide to an object only interfaces that the object knows how to call.

A connection has two parts: the object making calls to the methods of a specific interface, called the source or, alternatively, the connection point; and the object implementing the interface (receiving the calls), called the sink object (see Figure 9.1) Using my terminology from earlier paragraphs, the object is the source and makes calls to the sink interface methods. The client is the sink and implements the sink interface. One additional complexity is that a particular source object can have connections to multiple sink objects.

Figure 9.1. A connection to two sinks

The IConnectionPoint Interface

A client uses the source object’s implementation of the IConnectionPoint interface to establish a connection. Here is the definition of the IConnectionPoint interface:

interface IConnectionPoint : IUnknown {
    HRESULT GetConnectionInterface ([out] IID* pIID);
    HRESULT GetConnectionPointContainer (
        [out] IConnectionPointContainer** ppCPC);
    HRESULT Advise ([in] IUnknown* pUnkSink,
        [out] DWORD* pdwCookie);
    HRESULT Unadvise ([in] DWORD dwCookie);
    HRESULT EnumConnections ([out] IEnumConnections** ppEnum);
}

The GetConnectionInterface method returns the interface identifier (IID) of the sink interface for which a connection point makes calls. Using the previous example, calling GetConnectionInterface returns IID_ISomeSink. A client calls the Advise method to establish a connection. The client provides the appropriate sink interface pointer for the connection point and receives a magic cookie (token) that represents the connection. A client can later call the Unadvise method, specifying the magic cookie to break the connection. The EnumConnections method returns a standard COM enumeration object that a client uses to enumerate all the current connections that a connection point holds. The last method is GetConnectionPointContainer, which introduces a new complexity.

So far, this design allows a source object to make calls on only one specific interface. The source object maintains a list of clients that want to receive calls on that specific interface. When the source object determines that it should call one of the methods of its sink interface, the source iterates through its list of sink objects, calling that method for each sink object. What the design (again, as described so far) doesn’t include is the capability for an object to originate calls on multiple different interfaces using this mechanism. Alternatively, to present the question directly, we have a design in which an object can support multiple connections to a single connection point, but how can an object support multiple different connection points?

The solution is to demote the source object to subobject status and have an encapsulating object, called the connectable object (see Figure9.2), act as a container of these source subobjects. A client uses the source object’s GetConnectionPointContainer method to retrieve a pointer to the connectable object. A connectable object implements the IConnectionPointContainer interface.

Figure 9.2. A connectable object

Implementing IConnectionPointContainer indicates that a COM object supports connection points and, more specifically, that it can provide a connection point (a source subobject) for each sink interface the connectable object knows how to call. Clients then use the connection point as described previously to establish the connection.

The IConnectionPointContainer Interface

Here is the definition of the IConnectionPointContainer interface:

interface IConnectionPointContainer : IUnknown {
    HRESULT EnumConnectionPoints (
      [out] IEnumConnectionPoints ** ppEnum);
    HRESULT FindConnectionPoint ([in] REFIID riid,
      [out] IConnectionPoint** ppCP);
}

You call the FindConnectionPoint method to retrieve an IConnectionPoint interface pointer to a source subobject that originates calls on the interface specified by the riid parameter. The EnumConnectionPoints method returns a standard COM enumerator subobject that implements the IEnumConnectionPoints interface. You can use this enumerator interface to retrieve an IConnectionPoint interface pointer for each connection point that the connectable object supports.

Most often, a client that wants to establish a connection to a connectable object does the following (with error checking removed for clarity):

CComPtr<IUnknown>
  spSource = /* Set to the source of the events */ ;
CComPtr<_ISpeakerEvents>
  spSink = /* Sink to receive the events */ ;
DWORD dwCookie ;

CComPtr<IConnectionPointContainer> spcpc;
HRESULT hr = spSource.QueryInterface (&spcpc);

CComPtr<IConnectionPoint> spcp ;
hr = spcpc->FindConnectionPoint(__uuidof(_ISpeakerEvents),
  &spcp);
hr = spcp->Advise (spSink, &dwCookie) ;// Establish connection
// Time goes by, callbacks occur...
hr = spcp->Unadvise (dwCookie) ;       // Break connection

In fact, ATL provides two useful functions that make and break the connection between a source and a sink object. The AtlAdvise function makes the connection between a connectable object’s connection point (specified by the pUnkCP and iid parameters) and a sink interface implementation (specified by the pUnk parameter), and returns a registration code for the connection in the pdw location. The AtlUnadvise function requests the connectable object’s connection point to break the connection identified by the dw parameter.

ATLAPI AtlAdvise(IUnknown* pUnkCP, IUnknown* pUnk,
                 const IID& iid, LPDWORD pdw);
ATLAPI AtlUnadvise(IUnknown* pUnkCP, const IID& iid, DWORD dw);

You use these functions like this:

DWORD dwCookie;
// Make a connection
hr = AtlAdvise(spSource, spSink, __uuidof(_ISpeakerEvents),
  &dwCookie);
// ... Receive callbacks ...
// Break the connection
hr = AtlUnadvise(spSource, __uuidof(_ISpeakerEvents), dwCookie);

In summary, to establish a connection, you need an interface pointer for the connectable object, an interface pointer to an object that implements the sink interface, and the sink interface ID.

You commonly find connection points used by ActiveX controls. An ActiveX control is often a source of events. An event source implements event callbacks asmethod calls on a specified event sink interface. Typically, an ActiveX control container implements an event sink interface so that it can receive specific events from its contained controls. Using the connection points protocol, the control container establishes a connection from the source of events in the control (the connection point) to the event sink in the container. When an event occurs, the connection point calls the appropriate method of the sink interface for each sink connected to the connection point.

I should point out that the connection points design is deliberately a very general mechanism, which means that using connection points isn’t terribly efficient in some cases. [1] Connection points are most useful when an unknown number of clients might want to establish callbacks to a variety of different sink interfaces. In addition, the connection points protocol is well known; therefore, objects with no custom knowledge of each other can use it to establish connections. If you are writing both the source and sink objects, you might want to invent a custom protocol that is easier to use than the connection point protocol, to trade interface pointers.

[1]

For ActiveX controls and other in-process objects, connection points are acceptable, but when round-trips are a concern, they are horrid. Read Effective COM (Addison-Wesley, 1998), by Don Box, Keith Brown, Tim Ewald, and Chris Sells, for an in-depth discussion of these issues.

Creating an ATL-Based Connectable Object

The Brilliant Example Problem That Produces Blinding Insight

Let’s create a Demagogue COM object that represents a public speaker. The ATL-based CDemagogue class implements the ISpeaker interface. When asked to Speak, a speaker can whisper, talk, or yell his speech, depending on the value of Volume.

interface ISpeaker : IDispatch {
    [propget, id(1)] HRESULT Volume([out, retval] long *pVal);
    [propput, id(1)] HRESULT Volume([in] long newVal);
    [propget, id(2)] HRESULT Speech([out, retval] BSTR *pVal);
    [propput, id(2)] HRESULT Speech([in] BSTR newVal);
    [id(3)] HRESULT Speak();
};

Whispering, talking, and yelling generate event notifications on the _ISpeakerEvents source dispatch interface, and the recipients of the events hear the speech. Many client components can receive event notifications only when the source interface is a dispatch interface.

dispinterface _ISpeakerEvents {
properties:
methods:
    [id(1)] void OnWhisper(BSTR bstrSpeach);
    [id(2)] void OnTalk(BSTR bstrSpeach);
    [id(3)] void OnYell(BSTR bstrSpeach);
};

The underscore prefix is a naming convention that causes many type library browsers to not display the interface name. Because an event interface is an implementation detail, typically you don’t want such interfaces displayed to the authors of scripting languages when they use your component.

Note that the Microsoft Interface Definition Language (MIDL) compiler prefixes DIID_ to the name of a dispinterface when it generates its named globally unique identifier (GUID). So DIID__ISpeakerEvents is the named GUID for this interface.

Therefore, the following coclass definition describes a Demagogue. I’ve added an interface that lets me name a particular Demagogue if I don’t like the default (which is Demosthenes).

coclass Demagogue {
    [default]         interface      IUnknown;
                      interface      ISpeaker;
                      interface      INamedObject;
    [default, source] dispinterface _ISpeakerEvents;
};

I start with the CDemagogue class: an ATL-based, single-threaded-apartment-resident, COM-createable object to represent a Demagogue.

class ATL_NO_VTABLE CDemagogue :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CDemagogue, &CLSID_Demagogue>,
    public ISupportErrorInfo,
    public IDispatchImpl<ISpeaker, &IID_ISpeaker,
        &LIBID_ATLINTERNALSLib>,
    ...
{ ... };

Seven Steps to a Connectable Object

There are seven steps to creating a connectable object using ATL:

1. Implement the IConnectionPointContainer interface.

2. Implement QueryInterface so that it responds to requests for IID_IConnectionPointContainer.

3. Implement the IConnectionPoint interface for each source interface that the connectable object supports.

4. Provide a connection map that is a table that associates an IID with a connection point implementation.

5. Update the coclass definition for the connectable object class in your IDL file to specify each source interface. Each source interface must have the [source] attribute. The primary source interface should have the [default, source] attributes.

6. Typically, you implement helper methods that call the sink methods for all connected sinks.

7. You must call the helper methods at the appropriate times.

Adding Required Base Classes to Your Connectable Object

For an object to fire events using the connection points protocol, the object must be a connectable object. This means that the object must implement the IConnectionPointContainer interface. You can use an ATL-provided implementation of IConnectionPointContainer and IConnectionPoint by deriving the connectable object class from the appropriate base classes.

Step 1. Derive the CDemagogue connectable object class from the ATL template class IConnectionPointContainerImpl. This template class requires one parameter, the name of your derived class. This derivation provides the connectable object with an implementation of the IConnectionPointContainer interface.

class ATL_NO_VTABLE CDemagogue :
    ...
    public IConnectionPointContainerImpl<CDemagogue>,
    ...

Changes to the COM_MAP for a Connectable Object

Step 2. Any time you add a new interface implementation to a class, you should immediately add support for the interface to your QueryInterface method. ATL implements QueryInterface for an object by searching the object’s COM_MAP for an entry matching the requested IID. To indicate that the object supports the IConnectionPointContainer interface, add a COM_INTERFACE_ENTRY macro for the interface:

BEGIN_COM_MAP(CDemagogue)
...
    COM_INTERFACE_ENTRY(IConnectionPointContainer)
...
END_COM_MAP ()

Adding Each Connection Point

A connection point container needs a collection of connection points to contain (otherwise, the container is somewhat boring as well as misleading). For each source interface that the connectable object supports, you need a connection point subobject. A connection point subobject is logically a separate object (that is, its COM object identity is unique) that implements the IConnectionPoint interface.

Step 3. To create connection point subobjects, you derive your connectable object class from the template class IConnectionPointImpl one or more timesonce for each source interface supported by the connectable object. This derivation provides the connectable object with one or more implementations of the IConnectionPoint interface on separately reference-counted subobjects. The IConnectionPointImpl class requires three template parameters: the name of your connectable object class, the IID of the connection point’s source interface, and, optionally, the name of a class that manages the connections.

class ATL_NO_VTABLE CDemagogue :
  ...
  public IConnectionPointContainerImpl<CDemagogue>,
  public IConnectionPointImpl<CDemagogue, &DIID__ISpeakerEvents>
  ...

Where, O Where Are the Connection Points? Where, O Where Can They Be?

Any implementation of IConnectionPointContainer needs some fundamental information: a list of connection point objects and the IID that each connection point object supports. The ATL implementation uses a table called a connection point map in which you provide the required information. You define a connection point map in your connectable object’s class declaration using three ATL macros.

The BEGIN_CONNECTION_POINT_MAP macro specifies the beginning of the table. The only parameter is the class name of the connectable object. Each CONNECTION_POINT_ENTRY macro places an entry in the table and represents one connection point. The macro’s only parameter is the IID of the interface that the connection point supports.

Note that the CONNECTION_POINT_ENTRY macro requires you to specify an IID, whereas the COM_INTERFACE_ENTRY macro needs an interface class name. Historically, you could always prepend an IID_ prefix to an interface class name toproduce the name of the GUID for the interface. Earlier versions of ATL’s COM_INTERFACE_ENTRY macro actually did this to produce the appropriate IID.

However, source interfaces have no such regular naming convention. Various versions of MFC, MKTYPLIB, and MIDL have generated different prefixes to a dispinterface. The CONNECTION_POINT_ENTRY macro couldn’t assume a prefix, so you had to specify the IID explicitly. By default, ATL uses the __uuidof keyword to obtain the IID for a class.

The END_CONNECTION_MAP macro generates an end-of-table marker and code that returns the address of the connection map as well as its size.

Step 4. Here’s the connection map for the CDemagogue class:

BEGIN_CONNECTION_POINT_MAP(CDemagogue)
    CONNECTION_POINT_ENTRY(__uuidof(_ISpeakerEvents))
END_CONNECTION_POINT_MAP()

Update the coclass to Support the Source Interface

Step 5. Clients often read the type library, which describes an object that is a source of events, to determine certain implementation details, such as the object’s source interface(s). You need to ensure that the source object’s coclass description is up-to-date by adding an entry to describe the source interface.

coclass Demagogue
{
    [default]         interface      IUnknown;
                      interface      ISpeaker;
                      interface      INamedObject;
    [default, source] dispinterface _ISpeakerEvents;
};

Where There Are Events, There Must Be Fire

So far, we have a Demagogue connectable object that is a container of connection points and one connection point. The implementation, as presented up to now, permits a client to register a callback interface with a connection point. All the enumerators will work. The client can even disconnect. However, the connectable object never issues any callbacks. This isn’t terribly useful and has been a bit of work for no significant gain, so we’d better finish things. A connectable object needs to call the sink interface methods, otherwise known as firing the events.

To fire an event, you call the appropriate event method of the sink interface for each sink interface pointer registered with a connection point. This task is complex enough that you’ll generally find it useful to add event-firing helper methods to yourconnectable object class. You have one helper method in your connectable object class for each method in each of your connection points’ supported interfaces.

You fire an event by calling the associated event method of a particular sink interface. You do this for each sink interface registered with the connection point. This means you need to iterate through a connection point’s list of sink interfaces and call the event method for each interface pointer. “How and where does a connection point maintain this list?” you ask. Good timing, I was about to get to that.

Each IConnectionPointImpl base class object (which means each connection point) contains a member variable m_vec that ATL declares as a vector of IUnknown pointers. However, you don’t need to call QueryInterface to get the appropriate sink interfaces out of this collection; ATL’s implementation of IConnectionPointImpl::Advise has already performed this query for you. For example, the vector in the connection point associated with DIID_ISpeakerEvents actually contains _ISpeakerEvents pointers.

By default, m_vec is a CComDynamicUnkArray object, which is a dynamically allocated array of IUnknown pointers, each a client sink interface pointer for the connection point. The CComDynamicUnkArray class grows the vector as required, so the default implementation provides an unlimited number of connections.

Alternatively, when you declare the IConnectionPointImpl base class, you can specify that m_vec is a CComUnkArray object that holds a fixed number of sink interface pointers. Use the CComUnkArray class when you want to support a fixed maximum number of connections. ATL also provides an explicit template, CComUnkArray<1>, that is specialized for a single connection

Step 6. To fire an event, you iterate through the array and, for each non- NULL entry, call the sink interface method associated with the event you want to fire. Here’s a simple helper method that fires the OnTalk event of the _ISpeakerEvents interface.Note that m_vec is unambiguous only when you have a single connection point.

HRESULT Fire_OnTalk(BSTR bstrSpeech)
{
    CComVariant arg, varResult;
    int nIndex, nConnections = m_vec.GetSize();

    for (nIndex = 0; nIndex < nConnections; nIndex++) {
        CComPtr<IUnknown> sp = m_vec.GetAt(nIndex);
        IDispatch* pDispatch =
            reinterpret_cast<IDispatch*>(sp.p);
        if (pDispatch != NULL) {
            VariantClear(&varResult);
            arg = bstrSpeech;
            DISPPARAMS disp = { &arg, NULL, 1, 0 };
            pDispatch->Invoke(0x2, IID_NULL, LOCALE_USER_DEFAULT,
                DISPATCH_METHOD, &disp, &varResult, NULL, NULL);
        }
    }
    return varResult.scode;
}

The ATL Connection Point Proxy Generator

Writing the helper methods that call a connection point interface method is tedious and prone to errors. An additional complexity is that a sink interface can be a custom COM interface or a dispinterface. Considerably more work is involved in making a dispinterface callback (that is, using IDispatch::Invoke) than making a vtable callback. Unfortunately, the dispinterface callback is the most frequent case because it’s the only event mechanism that scripting languages, Internet Explorer, and most ActiveX control containers support.

The Visual Studio 2005 IDE, however, provides a source codegeneration tool that generates a connection point class that contains all the necessary helper methods for making callbacks on a specific connection point interface. In the Visual Studio 2005 Class View pane, right-click on the C++ class that you want to be a source of events. Select the Add Connection Point menu item from the context menu. The Implement Connection Point Wizard appears (see Figure 9.3).

Figure 9.3. The Implement Connection Point dialog box

[View full size image]

The Implement Connection Point Wizard creates one or more classes (declared and defined in the specified header file) that represent the specified interface(s) and their methods. To use the code generator, you must have a type library that describes the desired event interface. The code generator reads the type library description of an interface and generates a class, derived from IConnectionPointImpl, that contains an event-firing helper function for each interface method. You specify the generated class name as one of your connectable object’s base classes. This base class implements a specific connection point and contains all necessary event-firing helper methods.

The Implement Connection Point Proxy-Generated Code

The proxy generator produces a template class with a name in the form CProxy_<SinkInterfaceName>. This proxy class requires one parameter: your connectable object’s class name. The proxy class derives from an IConnectionPointImpl template instantiation that specifies your source interface.

Here is the code that the Implement Connection Point Wizard generates for the previously described _ISpeakerEvents interface:

#pragma once

template<class T>
class CProxy_ISpeakerEvents :
    public IConnectionPointImpl<T, &__uuidof(_ISpeakerEvents)>
{
public:
    HRESULT Fire_OnWhisper(BSTR bstrSpeech) {
        HRESULT hr = S_OK;
        T * pThis = static_cast<T*>(this);
        int cConnections = m_vec.GetSize();

        for (int iConnection = 0;
            iConnection < cConnections;
            iConnection++)
        {
            pThis->Lock();
            CComPtr<IUnknown> punkConnection =
              m_vec.GetAt(iConnection);
            pThis->Unlock();

            IDispatch * pConnection =
                static_cast<IDispatch*>(punkConnection.p);

            if (pConnection) {
                CComVariant avarParams[1];
                avarParams[0] = bstrSpeech;
                DISPPARAMS params = { avarParams, NULL, 1, 0 };
                hr = pConnection->Invoke(DISPID_ONWHISPER,
                    IID_NULL,
                    LOCALE_USER_DEFAULT,
                    DISPATCH_METHOD,
                    &params, NULL, NULL, NULL);
          }
        }
        return hr;
    }

// Other methods similar, deleted for clarity

};

Using the Connection Point Proxy Code

Putting everything together so far, here are the pertinent parts of the CDemagogue connectable object declaration. The only change from previous examples is the use of the generated connection point proxy class, CProxy_ISpeakerEvents<CDemagogue>, as a base class for the connection point instead of the more generic IConnectionPointImpl class.

class ATL_NO_VTABLE CDemagogue :
...
    public IConnectionPointContainerImpl<CDemagogue>,
    public CProxy_ISpeakerEvents<CDemagogue>, ... {

BEGIN_COM_MAP(CDemagogue)
...
    COM_INTERFACE_ENTRY(IConnectionPointContainer)
...
END_COM_MAP()

BEGIN_CONNECTION_POINT_MAP(CDemagogue)
    CONNECTION_POINT_ENTRY(__uuidof(_ISpeakerEvents))
END_CONNECTION_POINT_MAP()
...
};

Firing the Events

Step 7. The final step to make everything work is to fire each event at the appropriate time. When to do this is application-specific, but here is one example.

The CDemagogue object makes its speech when a client calls the Speak method. The Speak method, based on the current volume property, either whispers, talks, or yells. It does this by calling the OnWhisper, OnTalk, or OnYell event methods, as appropriate, of all clients listening to the demagogue’s _ISpeakerEvents interface.

STDMETHODIMP CDemagogue::Speak() {
    if (m_nVolume <= -100)
        return Fire_OnWhisper(m_bstrSpeech);

    if (m_nVolume >= 100)
        return Fire_OnYell(m_bstrSpeech);

    return Fire_OnTalk(m_bstrSpeech);
}

Going the Last Meter/Mile, Adding One Last Bell

The changes described so far provide a complete implementation of the connection point protocol. However, one last change makes your connectable object easier for clients to use. A connectable object should provide convenient client access to information about the interfaces that the object supports.

More specifically, many clients that want to receive events from a connectable object can ask the object for its IProvideClassInfo2 interface. Microsoft Internet Explorer, Visual Basic, and ATL-based ActiveX control containers do this, for example. The client calls the GetGUID method of this interface with the parameter GUIDKIND_DEFAULT_SOURCE_DISP_IID to retrieve the IID of the primary event disp-interface that the connectable object supports. This is the IID of the dispinterface listed in the connectable object’s coclass description with the [default, source] attributes.

Supporting IProvideClassInfo2 gives arbitrary clients a convenient mechanism for determining the primary event source IID and then using the IID to establish a connection. Note that the IID returned by this call to GetGUID must be a dispinterface; it cannot be a standard IUnknown-derived (vtable) interface.

When a connectable object fails the query for IProvideClassInfo2, some clients ask for IProvideClassInfo. A client can use this interface to retrieve an ITypeInfo pointer about the connectable object’s class. With a considerable bit of effort, a client can use this ITypeInfo pointer and determine the default source interface that the connectable object supports. The IProvideClassInfo2 interface derives from the IProvideClassInfo interface, so by implementing the first interface, you’ve already implemented the second one.

Because most connectable objects should implement the IProvideClassInfo2 interface, ATL provides a template class for the implementation, IProvideClassInfo2Impl, which provides a default implementation of all the IProvideClassInfo and IProvideClassInfo2 methods. The declaration of the class looks like this:

template <const CLSID* pcoclsid, const IID* psrcid,
    const GUID* plibid = &CAtlModule::m_libid,
    WORD wMajor = 1, WORD wMinor = 0,
    class tihclass = CComTypeInfoHolder>
class ATL_NO_VTABLE IProvideClassInfo2Impl
    : public IProvideClassInfo2
{ ... }

To use this implementation in your connectable object, you must derive the connectable object class from the IProvideClassInfo2Impl class. The last two template parameters in the following example are the major and minor version numbers of the component’s type library. They default to 1 and 0, respectively, so I didn’t need to list them. However, when you change the type library’s version number, you also need to change the numbers in the template invocation. You won’t get a compile error if you fail to make the change, but things won’t work correctly.

By always listing the version number explicitly, I remember to make this change more often:

#define LIBRARY_MAJOR   1
#define LIBRARY_MINOR    0

class ATL_NO_VTABLE CDemagogue :
...
    public IConnectionPointContainerImpl<CDemagogue>,
    public CProxy_ISpeakerEvents<CDemagogue>,
    public IProvideClassInfo2Impl<&CLSID_Demagogue,
        &__uuidof(_ISpeakerEvents),
        &LIBID_ATLINTERNALSLib, LIBRARY_MAJOR, LIBRARY_MINOR>,
...
};

You also need to update the interface map so that QueryInterface responds to IProvideClassInfo and IProvideClassInfo2.

BEGIN_COM_MAP(CDemagogue)
...
  COM_INTERFACE_ENTRY(IProvideClassInfo2)
  COM_INTERFACE_ENTRY(IProvideClassInfo)
END_COM_MAP()

Finally, here are all connectable-object-related changes in one place:

#define LIBRARY_MAJOR   1
#define LIBRARY_MINOR    0

// Event dispinterface
dispinterface _ISpeakerEvents {
properties:
methods:
    [id(1)] void OnWhisper(BSTR bstrSpeech);
    [id(2)] void OnTalk(BSTR bstrSpeech);
    [id(3)] void OnYell(BSTR bstrSpeech);
};

// Connectable object class
coclass Demagogue {
    [default]         interface      IUnknown;
                      interface      ISpeaker;
                      interface      INamedObject;
    [default, source] dispinterface _ISpeakerEvents;
};

// Implementation class for coclass Demagogue
class ATL_NO_VTABLE CDemagogue :
...
    public IConnectionPointContainerImpl<CDemagogue>,
    public CProxy_ISpeakerEvents<CDemagogue>,
    public IProvideClassInfo2Impl<&CLSID_Demagogue,
        &__uuidof(_ISpeakerEvents),
        &LIBID_ATLINTERNALSLib, LIBRARY_MAJOR, LIBRARY_MINOR>,
    ... {
public:
BEGIN_COM_MAP(CDemagogue)
    COM_INTERFACE_ENTRY(IConnectionPointContainer)
    COM_INTERFACE_ENTRY(IProvideClassInfo2)
    COM_INTERFACE_ENTRY(IProvideClassInfo)
...
END_COM_MAP()

BEGIN_CONNECTION_POINT_MAP(CDemagogue)
    CONNECTION_POINT_ENTRY(__uuidof(_ISpeakerEvents))
END_CONNECTION_POINT_MAP()
...
};

Creating an Object That Is an Event Recipient

It is quite easy, in theory, to implement an object that receives events on a single interface. You define a class that implements the interface and connect the object to the event source. We have a Demagogue class that generates events on the _ISpeakerEvents dispatch interface. Let’s define a CEarPolitic class (clearly one ear of the body politic) that implements _ISpeakerEvents.

coclass EarPolitic {
    [default] dispinterface _ISpeakerEvents;
};

Now, implement the class using ATL as the CEarPolitic class.

class ATL_NO_VTABLE CEarPolitic :
  ...
  public _ISpeakerEvents,
  ... {
public:
  ...
BEGIN_COM_MAP(CEarPolitic)
  COM_INTERFACE_ENTRY(IDispatch)
  COM_INTERFACE_ENTRY(_ISpeakerEvents)
...
END_COM_MAP()

// _ISpeakerEvents
  STDMETHOD(GetTypeInfoCount)(UINT* pctinfo);
  STDMETHOD(GetTypeInfo)(UINT itinfo, LCID lcid,
    ITypeInfo** pptinfo);
  STDMETHOD(GetIDsOfNames)(REFIID riid, LPOLESTR* rgszNames,
    UINT cNames, LCID lcid, DISPID* rgdispid);
  STDMETHOD(Invoke)(DISPID dispidMember, REFIID riid, LCID lcid,
    WORD wFlags, DISPPARAMS* pdispparams, VARIANT* pvarResult,
    EXCEPINFO* pexcepinfo, UINT* puArgErr);
};

Unfortunately, an event interface is typically a dispinterface, so the normal interface-implementation techniques don’t work. When you run the MIDL compiler, all you get for the generated _ISpeakerEvents interface is this:

MIDL_INTERFACE("A924C9DE-797F-430d-913D-93158AD2D801")
_ISpeakerEvents : public IDispatch
{
};

Instead of being able to simply implement the methods of the interface as regular C++ member functions, we must implement the IDispatch interface and support, at a minimum, the Invoke method. Invoke is a tedious method to write for any nontrivial event interface.

Another alternative is to use the IDispatch interface implementation that the IDispatchImpl template class provides. Unfortunately, the template class requires parameters describing a dual interface, not a dispinterface. To use IDispatchImpl, you need to define a dummy dual interface that has the same dispatch methods, dispatch identifiers, and function signatures as the event dispinterface.

This has more implications than are usually apparent. A dispinterface is not immutable, unlike a regular COM interface. If you don’t control the definition of the dispinterface, it might change from release to release. (It’s not that likely to change, but it is possible.) This means your dual interface needs to change as well. This implies that you cannot document the dual interface because, after it is published, it is immutable because some client may implement it. Because you should not describe the dual interface in a type library (because that documents it), you cannot use the universal type library-driven-marshaler and need a remoting proxy/stub for the dual interface. These are all theoretical issues because the dual interface, in this case, is an implementation detail that is specific to the implementation class, but the issues give us motivation enough to look for another solution.

On a slightly different note, what if you want to receive the same events from more than one event source and you want to know which source fired the event? For example, let’s say you want to implement an EarPolitic class that acts as a judge listening to _ISpeakerEvents from both a Defendant object and a Plaintiff object. Each object is a source of OnWhisper, OnTalk, and OnYell events, but the judge needs to keep track of who is saying what.

This requires you to implement the _ISpeakerEvents interface multiple times: once for each event source. Providing separate implementations of any interface multiple times in a class requires each implementation to be in a separate COM identity. Two typical solutions to this problem are member-wise composition (in which each implementation is in a nested class) and something similar to tear-off interfaces (in which each implementation is in a separate class).

The IDispEventImpl and IDispEventSimpleImpl Classes

To avoid these issues, ATL provides two template classes, IDispEventImpl and IDispEventSimpleImpl, that provide an implementation of the IDispatch interface for an ATL COM object. Typically, you use one of these classes in an object that wants to receive event callbacks. Both classes implement the dispatch interface on a nested class object that maintains a separate COM identity from the deriving class. This means that you can derive from these classes multiple times when you need to implement multiple source-dispatch interfaces.

The IDispEventImpl class requires a type library that describes the dispatch interface. The class uses the typeinfo at runtime to map the VARIANT parameters received in the Invoke method call to the appropriate types and stack frame layout necessary for calling the event-handler member function.

template <UINT nID, class T, const IID* pdiid = &IID_NULL,
          const GUID* plibid = &GUID_NULL,
          WORD wMajor = 0, WORD wMinor = 0,
          class tihclass = CComTypeInfoHolder>
class ATL_NO_VTABLE IDispEventImpl :
    public IDispEventSimpleImpl<nID, T, pdiid>
{ ... }

The IDispEventSimpleImpl class doesn’t use a type library, so it’s a more lightweight class. You use it when you don’t have a type library or when you want to be more efficient at runtime.

template <UINT nID, class T, const IID* pdiid>
class ATL_NO_VTABLE IDispEventSimpleImpl :
    public _IDispEventLocator<nID, pdiid>
{ ... }

When using the IDispEventSimpleImpl class, you must provide an _ATL_FUNC_INFO structure containing information that describes the expected parameters for the event handler.

struct _ATL_FUNC_INFO {
    CALLCONV cc;            // Calling convention
    VARTYPE vtReturn;       // VARIANT type for return value
    SHORT nParams;          // Number of parameters
    VARTYPE pVarTypes[_ATL_MAX_VARTYPES]; // Array of parameter
                                          // VARIANT type
};

Notice that IDispEventImpl derives from the IDispEventSimpleImpl class. The IDispEventSimpleImpl class calls the event handler based on the information in an _ATL_FUNC_INFO structure. You can provide the structure statically (at compile time) by referencing the structure in the sink map (described later in this chapter).

When you provide no structure reference, the IDispEventSimpleImpl class calls the virtual method GetFuncInfoFromId to get an _ATL_FUNC_INFO structure for the event handler associated with the specified DISPID. You provide the structure dynamically by overriding GetFuncInfoFromId and returning the appropriatestructure when called. You must use GetFuncInfoFromId when you want to call different event methods based on the locale provided by the event source.

Here’s the default implementation provided by the IDispEventSimpleImpl class:

//Helper for finding the function index for a DISPID
virtual HRESULT GetFuncInfoFromId(const IID& iid,
  DISPID dispidMember,
  LCID lcid,
  _ATL_FUNC_INFO& info) {
  ATLTRACE(_T("TODO: Classes using IDispEventSimpleImpl "
    "should override this method\n"));
  ATLASSERT(0);
  ATLTRACENOTIMPL(_T("IDispEventSimpleImpl::GetFuncInfoFromId"));
}

The IDispEventImpl class overrides this virtual method to create the structure from the typeinfo in the specified type library.

Implementing an Event Sink

The easiest way to implement one or more event sinks in a nonattributed ATL object is to derive the object one or more times from IDispEventImpl once for each unique event interface coming from each unique event source. Here’s the template class specification once more:

template <UINT nID, class T, const IID* pdiid = &IID_NULL,
          const GUID* plibid = &GUID_NULL,
          WORD wMajor = 0, WORD wMinor = 0,
          class tihclass = CComTypeInfoHolder>
class ATL_NO_VTABLE IDispEventImpl :
    public IDispEventSimpleImpl<nID, T, pdiid>
{ ... }

The nID parameter specifies an identifier for the event source that is unique to the deriving class T. You’ll see in Chapter 11, “ActiveX Controls,” that when the event source is a contained control and the event recipient is a composite control, the identifier is the contained control’s child window identifier.

A composite control can default all other IDispEventImpl template parameters, but an arbitrary COM object must specify all parameters except the last. The pdiid parameter specifies the GUID for the event dispinterface that this class implements. The dispinterface must be described in the type library specified by the plibid parameter and the type library major and minor version numbers, wMajor and wMinor. The tihclass parameter specifies the class to manage the type information for the deriving class T. The default CComTypeInfoHolder class is generally acceptable.

The more efficient way to implement one or more event sinks in an ATL object uses the IDispEventSimpleImpl class and needs no type library at runtime. However, you must provide the necessary _ATL_FUNC_INFO structure, as described previously. When using the IDispEventSimpleImpl class, you need to specify only the nID event source identifier, the deriving class T, and the pdiid GUID for the event dispinterface:

template <UINT nID, class T, const IID* pdiid>
class ATL_NO_VTABLE IDispEventSimpleImpl :
    public _IDispEventLocator<nID, pdiid>
{ ... }

Using the easier technique, let’s redefine the CEarPolitic class to implement the _ISpeakerEvents dispatch interface twice: once for a Demagogue acting as a Defendant and once for a different Demagogue acting as a Plaintiff. We have a type library, so we use the IDispEventImpl class to implement the sink for the Defendant object’s _ISpeakerEvents callbacks. We use the IDispEventSimpleImpl class for the Plaintiff object’s _ISpeakerEvents callbacks to demonstrate the alternative implementation. We typically introduce a typedef for each event interface implementation, to minimize typing and mistakes.

static const int DEFENDANT_SOURCE_ID = 0 ;
static const int PLAINTIFF_SOURCE_ID = 1 ;

class CEarPolitic;

typedef IDispEventImpl<DEFENDANT_SOURCE_ID,
  CEarPolitic,
  &__uuidof(_ISpeakerEvents),
  &LIBID_ATLINTERNALSLib,
  LIBRARY_MAJOR, LIBRARY_MINOR> DefendantEventImpl;

typedef IDispEventSimpleImpl<PLAINTIFF_SOURCE_ID,
 CEarPolitic, &__uuidof(_ISpeakerEvents)> PlaintiffEventImpl;

In this example, we arbitrarily chose 0 and 1 for the event source identifiers. The identifiers could have been any numbers. Now, we need to derive the CEarPolitic class from the two event-implementation classes:

class ATL_NO_VTABLE CEarPolitic :
    ...
    public DefendantEventImpl,
    public PlaintiffEventImpl {

// Event sink map required in here

};

The Event Sink Map

The IDispEventSimpleImpl class’s implementation of the Invoke method receives the event callbacks. When the event source calls the Invoke method, it specifies the event that has occurred using the DISPID parameter. The IDispEventSimpleImpl implementation searches an event sink table for the function to call when event DISPID occurs on dispatch interface DIID from event source identifier SOURCE.

You specify the beginning of the event sink map using the BEGIN_SINK_MAP macro within the declaration of the class that derives from IDispEventImpl or IDispEventSimpleImpl. You map each unique SOURCE/DIID/DISPID TRiple to the proper event-handling method using the SINK_ENTRY, SINK_ENTRY_EX, and SINK_ENTRY_INFO macros.

• SINK_ENTRY(SOURCE, DISPID, func). Use this macro in a composite control to name the handler for the specified event in the specified contained control’s default source interface. This macro assumes the use of IDispEventImpl and assumes that you call the AtlAdviseSinkMap function to establish the connection. The AtlAdviseSinkMap function assumes that your class is derived from CWindow. All in all, the SINK_ENTRY macro isn’t very useful for nonuser-interface (UI) objects that want to receive events.

• SINK_ENTRY_EX(SOURCE, DIID, DISPID, func). Use this macro to indicate the handler for the specified event in the specified object’s specified source interface. This macro is most useful for non-UI objects that want to receive events and for composite controls that want to receive events from a contained control’s nondefault source interface.

• SINK_ENTRY_INFO(SOURCE, DIID, DISPID, func, info). This macro is similar to the SINK_ENTRY_EX macro, with the addition that you can specify the _ATL_FUNC_INFO structure to be used when calling the event handler. You typically use this macro when using the IDispEventSimpleImpl class.

You end the event sink map using the END_SINK_MAP macro.

The general form of the table is as follows:

BEGIN_SINK_MAP(CEarPolitic)
   SINK_ENTRY_EX(SOURCE, DIID, DISPID, EventHandlerFunc)
   SINK_ENTRY_INFO(SOURCE, DIID, DISPID, EventHandlerFunc, &info)
...
END_SINK_MAP()

In the CEarPolitic example, there are three events, all from the same dispatch interface but coming from two different event sources. Therefore, we need six event sink map entries. We can use the SINK_ENTRY_EX macro to identify the event handlers for the Defendant event source. We don’t need to specify the _ATL_FUNC_INFO structure because the IDispEventImpl base class uses the type library to provide the appropriate structure at runtime. We need to use the SINK_ENTRY_INFO macro for the Plaintiff object. Because we used the IDisp-EventSimpleImpl base class, we need to provide the function information structure describing each event method.

Each function information structure describes one event method. The structure contains the calling convention, the VARIANT type of the return value of the method, the number of parameters, and the VARIANT types of each of the parameters. The calling convention should be set to CC_STDCALL because that’s what the IDispEventSimpleImpl class expects the event handlers to use.

Here are the function prototypes for the Plaintiff’s three event methods and their information structures (all identical in this example). Event handlers typically do not return a value – that is, they are void functions. Note: The proper vtreturn value in the _ATL_FUNC_INFO structure to represent a void function return is VT_EMPTY, not VT_VOID.

void __stdcall OnHearPlaintiffWhisper(BSTR bstrText);
void __stdcall OnHearPlaintiffTalk(BSTR bstrText);
void __stdcall OnHearPlaintiffYell(BSTR bstrText);

static const int DISPID_WHISPER = 1 ;
static const int DISPID_TALK    = 2 ;
static const int DISPID_YELL    = 3 ;

_ATL_FUNC_INFO OnHearWhisperInfo = {
  CC_STDCALL, VT_EMPTY, 1, { VT_BSTR }};
_ATL_FUNC_INFO OnHearTalkInfo = {
  CC_STDCALL, VT_EMPTY, 1, { VT_BSTR }};
_ATL_FUNC_INFO OnHearYellInfo = {
  CC_STDCALL, VT_EMPTY, 1, { VT_BSTR }};

Here’s the event sink map for the CEarPolitic object:

BEGIN_SINK_MAP(CEarPolitic)
  SINK_ENTRY_EX(DEFENDANT_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_WHISPER, OnHearDefendantWhisper)
  SINK_ENTRY_EX(DEFENDANT_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_TALK, OnHearDefendantTalk)
  SINK_ENTRY_EX(DEFENDANT_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_YELL, OnHearDefendantYell)
  SINK_ENTRY_INFO(PLAINTIFF_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_WHISPER, OnHearPlaintiffWhisper, &OnHearWhisperInfo)
  SINK_ENTRY_INFO(PLAINTIFF_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_TALK, OnHearPlaintiffTalk, &OnHearTalkInfo)
  SINK_ENTRY_INFO(PLAINTIFF_SOURCE_ID, __uuidof(_ISpeakerEvents),
    DISPID_YELL, OnHearPlaintiffYell, &OnHearYellInfo)
END_SINK_MAP()

One caution: The sink map contains a hard-coded DISPID for each event. This means that the sink map technically is specific to a particular dispinterface version. COM allows the DISPID s in a dispinterface to change from version to version. Now, this isn’t something that often happensand a control vendor that does such a thing is just asking for tech support calls and angry customers. But it is allowed.

The only absolutely correct way to obtain a DISPID is to ask the object implementing the dispinterface at startup for the DISPID corresponding to an event. For a source interface, this is impossible because when you build the sink, you’re implementing the source interface, so there’s no object to query. The only realistic option is to read the object’s type library at runtime. ATL, Visual Basic, and MFC don’t support this. They all assume that the DISPID s in a dispinterface will never change, as a questionable performance optimization.

The Callback Methods

The callback method specified by the sink entry macros must use the __stdcall calling convention. The parameters for each callback method specified in the sink map must agree in type and number with the corresponding event method as described in the type library. Here are the Defendant’s event methods; they are identical to the Plaintiff’s, as expected:

void __stdcall OnHearDefendantWhisper(BSTR bstrText);
void __stdcall OnHearDefendantTalk(BSTR bstrText);
void __stdcall OnHearDefendantYell(BSTR bstrText);

After two remaining steps, the CEarPolitic class will be complete: Implement the callback methods and establish the connection between a CEarPolitic instance and a Demagogue (which invokes the _ISpeakerEvents methods).

We use the following simple implementation for each of the event handlers:

void __stdcall CEarPolitic::OnHearDefendantTalk(BSTR bstrText) {
  CComBSTR title ;
  CreateText(title, OLESTR("defendant"),
    OLESTR("talking"), m_defendant);

  MessageBox(NULL, COLE2CT(bstrText), COLE2CT(title), MB_OK);
}

void CEarPolitic::CreateText(CComBSTR& bstrText,
  LPCOLESTR strRole,
  LPCOLESTR strAction,
  LPUNKNOWN punk) {
    bstrText = m_bstrName;
    bstrText += OLESTR(" hears the ");
    bstrText += strRole;
    bstrText += OLESTR(" (");

    CComQIPtr<INamedObject> spno = punk;
    CComBSTR bstrName;
    HRESULT hr = spno->get_Name (&bstrName) ;

    bstrText.AppendBSTR(bstrName);
    bstrText += OLESTR(") ");

    bstrText += strAction;
}

Connecting the Event Sink to an Event Source

When your class is a composite control, you should use the AtlAdviseSinkMap function to establish and remove the connections between all the source interfaces of the contained controls listed in the sink map and your IDispEventImpl implementation(s). This method uses the event source identifier as a child window identifier. Using the CWindow::GetDlgItem method, AtlAdviseSinkMap navigates to a child window handle and, from there, to the contained control’s IUnknown interface. From the IUnknown interface, it gets the IConnectionPointContainer interface and the appropriate connection point, and calls its Advise method.

template <class T>
inline HRESULT AtlAdviseSinkMap(T* pT, bool bAdvise);

You must use the AtlAdviseSinkMap function to establish the connections any time you use the IDispEventImpl class and you specify only the first two template parameters, using default values for the rest. Not specifying the source interface implies using the default source interface for the event source. The AtlAdvise-SinkMap method determines the default source interface, if unspecified, for each event source and establishes the connection point to that interface.

When your class isn’t a composite control, as in the ongoing example, you must explicitly call the DispEventAdvise method of each of your IDispEventSimpleImpl (or derived) base classes to connect each event source to each event sink implementation. The pUnk parameter to the DispEventAdvise method is any interface on the event source; the piid parameter is the desired source dispatch interface GUID. The DispEventUnadvise method breaks the connection.

template <UINT nID, class T, const IID* pdiid>
class ATL_NO_VTABLE IDispEventSimpleImpl : ... {
...
    HRESULT DispEventAdvise(IUnknown* pUnk, const IID* piid);
    HRESULT DispEventUnadvise(IUnknown* pUnk, const IID* piid);
...
}

Here is the IListener interface. We added it to the EarPolitic coclass to provide a means of determining whether a COM object can listen to a Defendant and a Plaintiff. It also provides the ListenTo and StopListening methods to establish and break the connection point between a Speaker event source and the Defendant or Plaintiff event sink.

interface IListener : IDispatch {
  typedef enum SpeakerRole { Defendant, Plaintiff } SpeakerRole;

  [id(1)] HRESULT ListenTo(SpeakerRole role, IUnknown* pSpeaker);
  [id(2)] HRESULT StopListening(SpeakerRole role);
};

The implementation of these methods is straightforward. ListenTo calls the DispEventAdvise method on the appropriate event sink to establish the connection:

STDMETHODIMP CEarPolitic::ListenTo(SpeakerRole role,
  IUnknown *pSpeaker) {
  HRESULT hr = StopListening(role) ; // Validates role
  if (FAILED(hr)) return hr ;

  switch (role) {
  case Defendant:
    hr = DefendantEventImpl::DispEventAdvise (pSpeaker,
      &DIID__ISpeakerEvents);
    if (SUCCEEDED(hr))
      m_defendant = pSpeaker;
    else
      Error(OLESTR("The defendant does not support listening"),
        __uuidof(IListener), hr);
    break;

  case Plaintiff:
    hr = PlaintiffEventImpl::DispEventAdvise (pSpeaker,
      &DIID__ISpeakerEvents);
    if (SUCCEEDED(hr))
      m_plaintiff = pSpeaker;
    else
      Error(OLESTR("The Plaintiff does not support listening"),
        __uuidof(IListener), hr);
    break;
  }
  return hr;
}

The StopListening method calls DispEventUnadvise to break the connection:

STDMETHODIMP CEarPolitic::StopListening(SpeakerRole role) {
  HRESULT hr = S_OK;
  switch (role) {
  case Defendant:
    if (m_defendant)
      hr = DefendantEventImpl::DispEventUnadvise (m_defendant,
        &DIID__ISpeakerEvents);

    if (FAILED(hr))
       Error (OLESTR("Unexpected error trying to stop listening "
         "to the defendant"), __uuidof(IListener), hr);

    m_defendant = NULL;
    break;

  case Plaintiff:
    if (m_plaintiff)
      hr = PlaintiffEventImpl::DispEventUnadvise(m_plaintiff,
        &DIID__ISpeakerEvents);
    if (FAILED(hr))
      Error(OLESTR("Unexpected error trying to stop listening "
        "to the Plaintiff"), __uuidof(IListener), hr);

    m_plaintiff = NULL;
    break;

  default:
    hr = E_INVALIDARG;
    break;
  }

  return hr;
}

In summary, use the IDispEventImpl and IDispEventSimpleImpl classes to implement an event sink for a dispatch interface. Call the DispEventAdvise and DispEventUnadvise methods of each class to establish and break the connection.

Derive your class directly from the source interface when the source is a simple COM interface. Call the AtlAdvise and AtlUnadvise global functions to establish and break the connection. When you need to implement the same source interface multiple times, use one of the various standard techniques (nested composition, method coloring, separate classes, or intermediate base classes) to avoid name collisions.

How It All Works: The Messy Implementation Details

Classes Used by an Event Source

The IConnectionPointContainerImpl Class

Let’s start by examining the IConnectionPointContainerImpl template class implementation of the IConnectionPointContainer interface.

First, the class needs to provide a vtable that is compatible with the IConnectionPointContainer interface. This vtable must contain five methods: the three IUnknown methods and the two IConnectionPointContainer methods.

template <class T>
class ATL_NO_VTABLE IConnectionPointContainerImpl
  : public IconnectionPointContainer {
  typedef CComEnum<IEnumConnectionPoints,
    &__uuidof(IEnumConnectionPoints), IConnectionPoint*,
    _CopyInterface<IConnectionPoint> >
    CComEnumConnectionPoints;
public:
  STDMETHOD(EnumConnectionPoints)(
    IEnumConnectionPoints** ppEnum) {
    if (ppEnum == NULL) return E_POINTER;

    *ppEnum = NULL;
    CComEnumConnectionPoints* pEnum = NULL;
    ATLTRY(pEnum = new CComObject<CComEnumConnectionPoints>)
    if (pEnum == NULL) return E_OUTOFMEMORY;

    int nCPCount;
    const _ATL_CONNMAP_ENTRY* pEntry = T::GetConnMap(&nCPCount);

    // allocate an initialize a vector of connection point
    // object pointers
    USES_ATL_SAFE_ALLOCA;
    if ((nCPCount < 0) || (nCPCount >
      (INT_MAX / sizeof(IConnectionPoint*))))
      return E_OUTOFMEMORY;
    size_t nBytes=0;
    HRESULT hr=S_OK;
    if( FAILED(hr=::ATL::AtlMultiply(&nBytes,
      sizeof(IConnectionPoint*),
      static_cast<size_t>(nCPCount)))) {
      return hr;
    }
    IConnectionPoint** ppCP =
      (IConnectionPoint**)_ATL_SAFE_ALLOCA(
      nBytes, _ATL_SAFE_ALLOCA_DEF_THRESHOLD);
    if (ppCP == NULL) {
      delete pEnum;
      return E_OUTOFMEMORY;
    }

    int i = 0;
    while (pEntry->dwOffset != (DWORD_PTR)-1) {
      if (pEntry->dwOffset == (DWORD_PTR)-2) {
        pEntry++;
        const _ATL_CONNMAP_ENTRY* (*pFunc)(int*) =
          (const _ATL_CONNMAP_ENTRY* (*)(int*))(
          pEntry->dwOffset);
        pEntry = pFunc(NULL);
        continue;
      }
      ppCP[i++] = (IConnectionPoint*)(
        (INT_PTR)this+pEntry->dwOffset);
      pEntry++;
    }

    // copy the pointers: they will AddRef this object
    HRESULT hRes = pEnum->Init((IConnectionPoint**)&ppCP[0],
      (IConnectionPoint**)&ppCP[nCPCount],
      reinterpret_cast<IConnectionPointContainer*>(this),
      AtlFlagCopy);
    if (FAILED(hRes)) {
      delete pEnum;
      return hRes;
    }
    hRes = pEnum->QueryInterface(
      __uuidof(IEnumConnectionPoints),
      (void**)ppEnum);
    if (FAILED(hRes)) delete pEnum;
    return hRes;
  }

  STDMETHOD(FindConnectionPoint)(REFIID riid,
    IConnectionPoint** ppCP) {
    if (ppCP == NULL) return E_POINTER;
    *ppCP = NULL;
    HRESULT hRes = CONNECT_E_NOCONNECTION;
    const _ATL_CONNMAP_ENTRY* pEntry = T::GetConnMap(NULL);
    IID iid;
    while (pEntry->dwOffset != (DWORD_PTR)-1) {
      if (pEntry->dwOffset == (DWORD_PTR)-2) {
        pEntry++;
        const _ATL_CONNMAP_ENTRY* (*pFunc)(int*) =
          (const _ATL_CONNMAP_ENTRY* (*)(int*))(
            pEntry->dwOffset);
        pEntry = pFunc(NULL);
        continue;
      }
      IConnectionPoint* pCP =
        (IConnectionPoint*)((INT_PTR)this+pEntry->dwOffset);
      if (SUCCEEDED(pCP->GetConnectionInterface(&iid)) &&
        InlineIsEqualGUID(riid, iid)) {
        *ppCP = pCP;
        pCP->AddRef();
        hRes = S_OK;
        break;
      }
      pEntry++;
    }
    return hRes;
  }
};

The IUnknown methods are easy: The class doesn’t implement them. You bring in the proper implementation of these three methods when you define a CComObject class parameterized on your connectable object class – for example, CCom-Object<CConnectableObject>.

The CComEnumConnectionPoints typedef declares a class for a standard COM enumerator that implements the IEnumConnectionPoints interface. You use this class of enumerator to enumerate IConnectionPoint interface pointers. A template expansion of the ATL CComEnum class provides the implementation. The implementation of the EnumConnectionPoints method creates and returns an instance of this enumerator.

EnumConnectionPoints begins with some basic error checking and then creates a new instance of a CComEnumConnectionPoints enumerator on the heap. The ATL enumerator implementation requires an enumerator to be initialized after instantiation. ATL enumerators are rather inflexible: To initialize an enumerator, you must pass it an array of the items the enumerator enumerates. In this particular case, the enumerator provides IConnectionPoint pointers, so the initialization array must be an array of IConnectionPoint pointers.

A connectable object’s connection map contains the information needed to produce the array of IConnectionPoint pointers. Each connection map entry contains the offset in the connectable object from the base of the IConnectionPointContainerImpl instance (that is, the current this pointer value) to the base of an IConnectionPointImpl instance.

EnumConnectionPoints allocates space for the initialization array on the stack, using _ATL_SAFE_ALLOCA. It iterates through each entry of the connection map, calculates the IConnectionPoint interface pointer to each IConnectionPointImpl object, and stores the pointer in the array. Note that these pointers are not reference-counted because the lifetime of the pointers in a stack-based array is limited to the method lifetime.

The call to the enumerator Init method initializes the instance. It’s critical here to use the AtlFlagCopy argument. This informs the enumerator to make a proper copy of the items in the initialization array. For interface pointers, this means to AddRef the pointers when making the copy. Refer to Chapter 8, “Collections and Enumerators,” for details on COM enumerator initialization.

The pEnum pointer is a CComEnumConnectionPoints pointer, although it would be a bit better if it were declared as a CComObject<CComEnumConnectionPoints> pointerbecause that’s what it actually is. Regardless, EnumConnectionPoints must return an IEnumConnectionPoints pointer, not pEnum itself, so it queries the enumerator (via pEnum) for the appropriate interface pointer and returns the pointer.

The FindConnectionPoint method is quite straightforward. After the usual initial error checking, FindConnectionPoint uses the connection map to calculate an IConnectionPoint interface pointer to each connection point in the connectable object. Using the interface pointer, it asks each connection point for the IID of its supported interface and compares it with the IID it’s trying to find. A match causes it to return the appropriate AddRef’ed interface pointer with status S_OK; otherwise, failure returns the CONNECT_E_NOCONNECTION status code.

One minor oddity is the check to see if the offset is -2 when walking through the connection point map. This is a value that appears only when using attributed ATL (discussed in AppendixD, “Attributed ATL”). Attributed ATL inserts a second connection point map into your class. The check for an offset of -2 is used to signal that it’s time to jump from the standard connection point map into the attributed map. This is done by calling the function pointer in that slot to get the new starting address of the next map to walk. This has the potential to be a general-purpose chaining mechanism for connection point maps; however, the connection-point macros don’t support it, so it would take a good deal of hacking.

Most of the real work is left to the connection point implementation, so let’s look at it next.

The IConnectionPointImpl Class

The IConnectionPointImpl template class implements the IConnectionPoint interface. To do that, the class needs to provide a vtable that is compatible with the IConnectionPoint interface. This vtable must contain eight methods: the three IUnknown methods and the five IConnectionPoint methods.

The first item of note is that the IConnectionPointImpl class derives from the _ICPLocator class:

template <class T, const IID* piid,
  class CDV = CComDynamicUnkArray >
class ATL_NO_VTABLE IConnectionPointImpl
  : public _ICPLocator<piid>
{ ... }

The _ICPLocator Class

template <const IID* piid>
class ATL_NO_VTABLE _ICPLocator {
public:
    //this method needs a different name than QueryInterface
    STDMETHOD(_LocCPQueryInterface)(REFIID riid,
        void ** ppvObject) = 0;
    virtual ULONG STDMETHODCALLTYPE AddRef(void) = 0;
    virtual ULONG STDMETHODCALLTYPE Release(void) = 0;
};

The _ICPLocator class contains the declaration of the virtual method, _LocCPQueryInterface. A virtual method occupies a slot in the vtable, so this declaration states that calls through the first entry in the vtable, the entry callers use to invoke QueryInterface, will be sent to the method _LocCPQueryInterface. The declaration is purely virtual, so a derived class needs to provide the implementation. This is important because each connection point needs to provide a unique implementation of _LocCPQueryInterface.

A connection point must maintain a COM object identity that is separate from its connection point container. Therefore, a connection point needs its own implementation of QueryInterface. If you named the first virtual method in the _ICPLocator class QueryInterface, C++ multiple inheritance rules would see the name as just another reference to a single implementation of QueryInterface for the connectable object. Normally, that’s exactly what you want. For example, imagine that you have a class derived from three interfaces. All three interfaces mention the virtual method QueryInterface, but you want a single implementation of the method that all base classes share. Similarly, you want a shared implementation of AddRef and Release as well. But you don’t want this for a connection point in a base class.

The idea here is that we want to expose two different COM identities (the connectable object and the connection point), which requires two separate implementations of QueryInterface. But we merge the remaining IUnknown implementation (AddRef and Release) because we don’t want to keep a separate reference count for each connection point. ATL uses this “unique” approach to avoid having to delegate AddRef and Release calls from the connection point object to the connectable object.

The IConnectionPointImpl Class’s Methods

The IUnknown methods are more complicated in IConnectionPointImpl than was the case in IConnectionPointContainerImpl so that a connection point can implement its own unique QueryInterface method. For a connection point, this is the _LocCPQueryInterface virtual method.

template <class T, const IID* piid,
  class CDV = CComDynamicUnkArray >
class ATL_NO_VTABLE IConnectionPointImpl
  : public _ICPLocator<piid> {
  typedef CComEnum<IEnumConnections,
    &__uuidof(IEnumConnections), CONNECTDATA,
    _Copy<CONNECTDATA> > CComEnumConnections;
  typedef CDV _CDV;
public:
  ~IConnectionPointImpl();
  STDMETHOD(_LocCPQueryInterface)(REFIID riid, void ** ppvObject) {
#ifndef _ATL_OLEDB_CONFORMANCE_TESTS
    ATLASSERT(ppvObject != NULL);
#endif
    if (ppvObject == NULL)
      return E_POINTER;
    *ppvObject = NULL;

    if (InlineIsEqualGUID(riid, __uuidof(IConnectionPoint)) ||
      InlineIsEqualUnknown(riid)) {
      *ppvObject = this;
      AddRef();
#ifdef _ATL_DEBUG_INTERFACES
      _AtlDebugInterfacesModule.AddThunk((IUnknown**)ppvObject,
        _T("IConnectionPointImpl"), riid);
#endif // _ATL_DEBUG_INTERFACES
      return S_OK;
    }
    else
      return E_NOINTERFACE;
  }

  STDMETHOD(GetConnectionInterface)(IID* piid2) {
    if (piid2 == NULL)
      return E_POINTER;
    *piid2 = *piid;
    return S_OK;
  }
  STDMETHOD(GetConnectionPointContainer)(
    IConnectionPointContainer** ppCPC) {
    T* pT = static_cast<T*>(this);
    // No need to check ppCPC for NULL since
    // QI will do that for us
    return pT->QueryInterface(
      __uuidof(IConnectionPointContainer), (void**)ppCPC);
  }

  STDMETHOD(Advise)(IUnknown* pUnkSink, DWORD* pdwCookie);
  STDMETHOD(Unadvise)(DWORD dwCookie);
  STDMETHOD(EnumConnections)(IEnumConnections** ppEnum);
  CDV m_vec;
};

The _LocCPQueryInterface Method

The _LocCPQueryInterface method has the same function signature as the COM QueryInterface method, but it responds to only requests for IID_IUnknown and IID_IConnectionPoint by producing an AddRef’ed pointer to itself. This gives each base class instance of an IConnectionPointImpl object a unique COM identity.

The AddRef and Release Methods

As usual, you bring in the proper implementation of these two methods when you define a CComObject class parameterized on your connectable object class – for example, CComObject<CConnectableObject>.

The GetConnectionInterface and GetConnectionPointContainer Methods

The GetConnectionInterface interface method simply returns the source interface IID for the connection point, so the implementation is trivial. The GetConnectionPointContainer interface method is also simple, but some involved typecasting is required to request the correct interface pointer.

The issue is that the current class, this particular IConnectionPointImpl expansion, doesn’t support the IConnectionPointContainer interface. But the design of the template classes requires your connectable object class, represented by class T in the template, to implement the IConnectionPointContainer interface:

T* pT = static_cast<T*>(this);
return pT->QueryInterface(IID_IConnectionPointContainer,
  (void**)ppCPC);

The typecast goes from the connection point subobject down the class hierarchy to the (deriving) connectable object class and calls that class’s QueryInterface implementation to obtain the required IConnectionPointContainer interface pointer.

The Advise, Unadvise, and EnumConnections Methods

The Advise, Unadvise, and EnumConnections methods all need a list of active connections. Advise adds new entries to the list, Unadvise removes entries from the list, and EnumConnections returns an object that enumerates over the list.

This list is of template parameter type CDV. By default, this is type CComDynamic-UnkArray, which provides a dynamically growable array implementation of the list. As I described previously, ATL provides a fixed-size list implementation and a specialized single-entry list implementation. However, it is relatively easy to provide a custom list implementation because the Advise, Unadvise, and EnumConnections implementations always access the list through its well-defined methods: Add, Remove, begin, end, GetCookie, and GetUnknown.

The CComEnumConnections typedef declares a class for a standard COM enumerator that implements the IEnumConnections interface. You use this class of enumerator to enumerate CONNECTDATA structures, which contain a client sink interface pointer and its associated magic cookie-registration token. A template expansion of the ATL CComEnum class provides the implementation. The implementation of the EnumConnections interface method creates and returns an instance of this enumerator.

The Advise Method

template <class T, const IID* piid, class CDV>
STDMETHODIMP IConnectionPointImpl<T, piid, CDV>::Advise(
    IUnknown* pUnkSink,
    DWORD* pdwCookie) {
    T* pT = static_cast<T*>(this);
    IUnknown* p;
    HRESULT hRes = S_OK;
    if (pdwCookie != NULL)
        *pdwCookie = 0;
    if (pUnkSink == NULL || pdwCookie == NULL)
        return E_POINTER;
    IID iid;
    GetConnectionInterface(&iid);
    hRes = pUnkSink->QueryInterface(iid, (void**)&p);
    if (SUCCEEDED(hRes)) {
        pT->Lock();
        *pdwCookie = m_vec.Add(p);
        hRes = (*pdwCookie != NULL) ? S_OK :
            CONNECT_E_ADVISELIMIT;
        pT->Unlock();
        if (hRes != S_OK)
            p->Release();
    }
    else if (hRes == E_NOINTERFACE)
        hRes = CONNECT_E_CANNOTCONNECT;
    if (FAILED(hRes))
        *pdwCookie = 0;
    return hRes;
}

The Advise method retrieves the sink interface IID for this connection point and queries the IUnknown pointer that the client provides for the sink interface. This ensures that the client passes an interface pointer to an object that actually implements the expected sink interface. Failure to provide the correct interface pointer produces a CONNECT_E_CANNOTCONNECT error. You don’t want to keep a connection to something that can’t receive the callback. Plus, by obtaining the correct interface pointer here, the connection point doesn’t have to query for it during each callback.

When the query succeeds, the connection point needs to add the connection to the list. So, it acquires a lock on the entire connectable object, adds the connection to the list if there’s room, and releases the lock.

The Unadvise Method

template <class T, const IID* piid, class CDV>
STDMETHODIMP IConnectionPointImpl<T, piid, CDV>::Unadvise(
    DWORD dwCookie) {
    T* pT = static_cast<T*>(this);
    pT->Lock();
    IUnknown* p = m_vec.GetUnknown(dwCookie);
    HRESULT hRes = m_vec.Remove(dwCookie) ? S_OK :
        CONNECT_E_NOCONNECTION;
    pT->Unlock();
    if (hRes == S_OK && p != NULL)
        p->Release();
    return hRes;
}

The Unadvise method is relatively simple. It locks the connectable object, asks the list class to translate the provided magic cookie value into the corresponding IUnknown pointer, removes the connection identified by the cookie, unlocks the connectable object, and releases the held sink interface pointer.

The EnumConnections Method

EnumConnection begins with some basic error checking and then creates a new instance of a CComObject<CComEnumConnections> enumerator on the heap. As before, the ATL enumerator implementation requires that an enumerator be initialized from an array after instantiationin this particular case, a contiguous array of CONNECTDATA structures.

template <class T, const IID* piid, class CDV>
STDMETHODIMP IConnectionPointImpl<T, piid, CDV>::EnumConnections(
    IEnumConnections** ppEnum) {
    if (ppEnum == NULL)
        return E_POINTER;
    *ppEnum = NULL;
    CComObject<CComEnumConnections>* pEnum = NULL;
    ATLTRY(pEnum = new CComObject<CComEnumConnections>)
    if (pEnum == NULL)
        return E_OUTOFMEMORY;
    T* pT = static_cast<T*>(this);
    pT->Lock();
    CONNECTDATA* pcd = NULL;
    ATLTRY(pcd = new CONNECTDATA[m_vec.end()-m_vec.begin()])
    if (pcd == NULL) {
        delete pEnum;
        pT->Unlock();
        return E_OUTOFMEMORY;
    }
    CONNECTDATA* pend = pcd;
    // Copy the valid CONNECTDATA's
    for (IUnknown** pp = m_vec.begin();pp<m_vec.end();pp++) {
        if (*pp != NULL)
        {
            (*pp)->AddRef();
            pend->pUnk = *pp;
            pend->dwCookie = m_vec.GetCookie(pp);
            pend++;
        }
    }
    // don't copy the data, but transfer ownership to it
    pEnum->Init(pcd, pend, NULL, AtlFlagTakeOwnership);
    pT->Unlock();
    HRESULT hRes = pEnum->_InternalQueryInterface(
        __uuidof(IEnumConnections), (void**)ppEnum);
    if (FAILED(hRes))
        delete pEnum;
    return hRes;
}

The connection list stores IUnknown pointers. The CONNECTDATA structure contains the interface pointer and its associated magic cookie. EnumConnections allocates space for the initialization array from the heap. It iterates through the connection list entries, copying the interface pointer and its associated cookie to the dynamically allocated CONNECTDATA array. It’s important to note that any non-NULL interface pointers are AddRef’ed. This copy of the interface pointers has a lifetime greater than the EnumConnections method.

The call to the enumerator Init method initializes the instance. It’s critical here to use the AtlFlagTakeOwnership argument. This informs the enumerator to use the provided array directly instead of making yet another copy of it. This also means that the enumerator is responsible for correctly releasing the elements in the array as well as the array itself.

The EnumConnections method now uses _InternalQueryInterface to return an IEnumConnections interface pointer on the enumerator object, which, at this point, is the only outstanding reference to the enumerator. [2]

[2]

EnumConnections uses _InternalQueryInterface instead of IUnknown::QueryInterface because the latter results in a virtual function call, whereas the former is a more efficient direct call.

Classes Used by an Event Sink

First, you need to understand the big picture about event sinks. Your object class might want to implement multiple event sink interfaces or the same event sink interface multiple times. All event sink interfaces need nearly identical functionality: IUnknown, IDispatch, Invoke, and the capability to look up the DISPID in a sink map and delegate the event method call to the appropriate event handler. But each implementation also needs some custom functionalityspecifically, each implementation must be a unique COM identity.

ATL defines a class named _IDispEvent that implements the common functionality and, through template parameters and interface coloring, allows each derivation from this one C++ class to maintain a unique COM identity. This means that ATL implements all specialized event sink implementations using a single C++ class, _IDispEvent.

The _IDispEvent Class

Let’s examine the _IDispEvent class. The first interesting aspect is that it is intended to be used as an abstract base class. The first three virtual methods are declared using the COM standard calling convention and are all purely virtual. The first method is _LocDEQueryInterface, and the following two are the AddRef and Release methods. This gives the _IDispEvent class the vtable of a COM object that supports the IUnknown interface. The _IDispEvent class cannot simply derive from IUnknown because it needs to provide a specialized version of QueryInterface. A derived class needs to supply the _LocDEQueryInterface, AddRef, and Release methods.

class ATL_NO_VTABLE _IDispEvent {
...
public:
    //this method needs a different name than QueryInterface
    STDMETHOD(_LocDEQueryInterface)(REFIID riid,
        void ** ppvObject) = 0;
    virtual ULONG STDMETHODCALLTYPE AddRef(void) = 0;
    virtual ULONG STDMETHODCALLTYPE Release(void) = 0;
...
};

The class maintains five member variables, only one of which is always used, m_dwEventCookie. Each member variable is initialized by the constructor:

_IDispEvent() :
  m_libid(GUID_NULL),
  m_iid(IID_NULL),
  m_wMajorVerNum(0),
  m_wMinorVerNum(0),
  m_dwEventCookie(0xFEFEFEFE)
{ }

The m_dwEventCookie variable holds the connection point registration value returned from the source object’s IConnectionPoint::Advise method until it’s needed to break the connection. The class assumes that no event source will ever use the value 0xFEFEFEFE as the connection cookie because it uses that value as a flag to indicate that no connection is established. [3]

[3]

Note that this places a constraint on a connection list implementation (that is, the CDV template parameter class)namely, that it never provides the value 0xFEFEFEFE as a connection cookie.

The m_libid, m_iid, m_wMajorVerNum, and m_wMinorVerNum variables hold the type library GUID, the source interface IID, and the type library major and minor version number, respectively.

GUID m_libid;
IID m_iid;
unsigned short m_wMajorVerNum;
unsigned short m_wMinorVerNum;
DWORD m_dwEventCookie;

This _IDispEvent class provides the DispEventAdvise and DispEventUnadvise methods, which establish and break, respectively, a connection between the specified source object’s (pUnk) source interface (piid) and the _DispEvent sink object.

HRESULT DispEventAdvise(IUnknown* pUnk, const IID* piid) {
    ATLENSURE(m_dwEventCookie == 0xFEFEFEFE);
    return AtlAdvise(pUnk, (IUnknown*)this, *piid, &m_dwEventCookie);
}

HRESULT DispEventUnadvise(IUnknown* pUnk, const IID* piid) {
    HRESULT hr = AtlUnadvise(pUnk, *piid, m_dwEventCookie);
    m_dwEventCookie = 0xFEFEFEFE;
    return hr;
}

You can implement multiple event sinks in a single ATL COM object. In the most general case, this means that you need a unique event sink for each different source of events (source identifier). Furthermore, you need a unique event sink object for each separate connection (source interface) to a source of events.

The _IDispEventLocator Class

Implementing multiple event sinks requires the sink to derive indirectly from _IDispEvent multiple times. But we need to do so in a way that allows us to find a particular _IDispEvent base class instance, given a source object identifier and the source interface on that object.

ATL uses the template class _IDispEventLocator to do this. Each unique _IDisp-EventLocator template invocation produces a different, addressable _IDispEvent event sink instance. [4]

[4]

Keith Brown pointed out that it would have been more appropriate to call these Locator classes COM-Identity classes – for example, _IDispEventCOMIdentity and IConnectionPointCOMIdentity. Their fundamental purpose is to provide a unique base class instance for each required COM identity. Yes, you need to locate the appropriate base class when needed, but the sole purpose in renaming the QueryInterface method is to implement a separate identity.

template <UINT nID, const IID* piid>
class ATL_NO_VTABLE _IDispEventLocator : public _IDispEvent {
public:
};

The IDispEventSimpleImpl Class

The IDispEventSimpleImpl class implements the IDispatch interface. It derives from the _IDispEventLocator<nID, pdiid> class to inherit the IUnknown vtable, the member variables, and the connection-point Advise and Unadvise support that the _IDispEvent base class provides.

template <UINT nID, class T, const IID* pdiid>
class ATL_NO_VTABLE IDispEventSimpleImpl :
    public _IDispEventLocator<nID, pdiid> {
// Abbreviated for clarity
    STDMETHOD(_LocDEQueryInterface)(REFIID riid,
        void ** ppvObject);
    virtual ULONG STDMETHODCALLTYPE AddRef();
    virtual ULONG STDMETHODCALLTYPE Release();
    STDMETHOD(GetTypeInfoCount)(UINT* pctinfo);
    STDMETHOD(GetTypeInfo)(UINT itinfo, LCID lcid,
        ITypeInfo** pptinfo);
    STDMETHOD(GetIDsOfNames)(REFIID riid, LPOLESTR* rgszNames,
        UINT cNames, LCID lcid, DISPID* rgdispid);
    STDMETHOD(Invoke)(DISPID dispidMember, REFIID riid,
        LCID lcid, WORD wFlags, DISPPARAMS* pdispparams,
        VARIANT* pvarResult, EXCEPINFO* pexcepinfo,
        UINT* puArgErr);
};

Notice that the IDispEventSimpleImpl class provides an implementation of the _LocDEQueryInterface, AddRef, and Release methods that it inherited from its _IDispEvent base class. Notice also that the next four virtual methods are the standard IDispatch interface methods. The IDispEventSimpleImpl class now has the proper vtable to support IDispatch. It cannot simply derive from IDispatch to obtain the vtable because the class needs to provide a specialized version of QueryInterface.

The IDispEventSimpleImpl class implements the _LocDEQueryInterface method so that each event sink is a separate COM identity from that of the deriving class. The event sink object is supposed to respond positively to requests for its source dispatch interface ID, the IUnknown interface, the IDispatch interface, and the GUID contained in the m_iid member variable.

    STDMETHOD(_LocDEQueryInterface)(REFIID riid,
        void ** ppvObject) {
        ATLASSERT(ppvObject != NULL);
        if (ppvObject == NULL)
            return E_POINTER;
        *ppvObject = NULL;

        if (InlineIsEqualGUID(riid, IID_NULL))
            return E_NOINTERFACE;

        if (InlineIsEqualGUID(riid, *pdiid) ||
            InlineIsEqualUnknown(riid) ||
            InlineIsEqualGUID(riid, __uuidof(IDispatch)) ||
            InlineIsEqualGUID(riid, m_iid)) {

            *ppvObject = this;
            AddRef();
#ifdef _ATL_DEBUG_INTERFACES
            _AtlDebugInterfacesModule.AddThunk(
                (IUnknown**)ppvObject, _T("IDispEventImpl"),
                riid);
#endif // _ATL_DEBUG_INTERFACES
            return S_OK;
        }
        else
            return E_NOINTERFACE;
    }

The IDispEventSimpleImpl class also provides a simple implementation of the AddRef and Release methods. This permits the class to be used directly as a COM object.

template <UINT nID, class T, const IID* pdiid>
class ATL_NO_VTABLE IDispEventSimpleImpl : ... {
...
    virtual ULONG STDMETHODCALLTYPE AddRef()  { return 1; }
    virtual ULONG STDMETHODCALLTYPE Release() { return 1; }
...
};

However, when you compose the class into a more complex ATL-based COM object, the AddRef and Release methods in the deriving class are used. In other words, an AddRef to the event sink of a typical ATL COM object calls the deriving object’s CComObject::AddRef method (or whatever your most-derived class is). Watch out for reference-counting cycles due to this. A client holds a reference to the event source, which holds a reference to (nominally) the event sink but is actually to the client itself.

The IDispEventSimpleImpl class implements the GetTypeInfoCount, GetTypeInfo, and GetIDsOfNames methods by returning the error E_NOTIMPL. An event-dispatch interface is required only to support the IUnknown methods and the Invoke method.

STDMETHOD(GetTypeInfoCount)(UINT*)
{ATLTRACENOTIMPL(_T("IDispEventSimpleImpl::GetTypeInfoCount"));}

STDMETHOD(GetTypeInfo)(UINT, LCID, ITypeInfo**)
{ATLTRACENOTIMPL(_T("IDispEventSimpleImpl::GetTypeInfo"));}

STDMETHOD(GetIDsOfNames)(REFIID, LPOLESTR*, UINT, LCID, DISPID*)
{ATLTRACENOTIMPL(_T("IDispEventSimpleImpl::GetIDsOfNames"));}

STDMETHOD(Invoke)(DISPID dispidMember, REFIID, LCID lcid, WORD /*wFlags*/,
                  DISPPARAMS* pdispparams, VARIANT* pvarResult,
                  EXCEPINFO* /*pexcepinfo*/, UINT* /*puArgErr*/);

The Invoke method searches the deriving class’s event sink map for the appropriate event handler for the current event. It finds the appropriate sink map by calling _GetSinkMap, which is a static member function defined in the deriving class by the BEGIN_SINK_MAP macro (described later in this section). The proper event handler is the entry that has the matching event source ID (nID) as the template invocation, the same source interface IID (pdiid) as the template invocation, and the same DISPID as the argument to Invoke.

When the matching event sink entry specifies an _ATL_FUNC_INFO structure (meaning that the event sink entry was defined using the SINK_ENTRY_INFO macro), Invoke uses the structure to call the handler. Otherwise, Invoke calls the GetFuncInfoFromId virtual function to obtain the required structure. When the GetFuncInfoFromId function fails, Invoke silently returns S_OK. This is as it should be because an event handler must respond with S_OK to events the handler doesn’t recognize.

You must override the GetFuncInfoFromId method when using the SINK_ENTRY_EX macro with the IDispEventSimpleImpl class. The default implementation silently fails:

virtual HRESULT GetFuncInfoFromId(const IID&, DISPID, LCID,
  _ATL_FUNC_INFO&) {
  ATLTRACE(_T("TODO: Classes using IDispEventSimpleImpl should "
    "override this method\n"));
  ATLASSERT(0);
  ATLTRACENOTIMPL(_T("IDispEventSimpleImpl::GetFuncInfoFromId"));
}

This means that if you use the IDispEventSimpleImpl class directly, and you specify an event hander using the SINK_ENTRY_EX macro, and you forget to override the GetFuncInfoFromId method or you implement it incorrectly, everything compiles cleanly but your event handler will never be called.

The IDispEventSimpleImpl class provides some overloaded helper methods for establishing and breaking a connection to an event source. The following two methods establish and break a connection between the current sink and the specified event interface (piid) on the specified event source (pUnk):

// Helpers for sinking events on random IUnknown*
    HRESULT DispEventAdvise(IUnknown* pUnk, const IID* piid) {
        ATLENSURE(m_dwEventCookie == 0xFEFEFEFE);
        return AtlAdvise(pUnk, (IUnknown*)this, *piid, &m_dwEventCookie);
    }
    HRESULT DispEventUnadvise(IUnknown* pUnk, const IID* piid) {
        HRESULT hr = AtlUnadvise(pUnk, *piid, m_dwEventCookie);
        m_dwEventCookie = 0xFEFEFEFE;
        return hr;
    }

The next two methods establish and break a connection between the current sink and the specified event source using the sink’s dispatch interface:

HRESULT DispEventAdvise(IUnknown* pUnk) {
  return _IDispEvent::DispEventAdvise(pUnk, pdiid);
}
HRESULT DispEventUnadvise(IUnknown* pUnk) {
  return _IDispEvent::DispEventUnadvise(pUnk, pdiid);
}

The Sink Map: Associated Structure, Macros, and the _GetSinkMap Method

The sink map is an array of _ATL_EVENT_ENTRY structures. The structure contains the following fields:

nControlID	The event source identifier; control ID for contained controls
piid	The source dispatch interface IID
nOffset	The offset of the event sink implementation from the deriving class
dispid	The event callback dispatch ID
pfn	The member function pointer of the event handler to invoke [5]
pInfo	The _ATL_FUNC_INFO structure used for the event-handler call

[5]

If you’ve been wondering why your event-handler functions have to use the __stdcall calling convention; the declaration of this pointer specifies it.

template <class T>
struct _ATL_EVENT_ENTRY {
    UINT nControlID; // ID identifying object instance
    const IID* piid; // dispinterface IID
    int nOffset;     // offset of dispinterface from this pointer
    DISPID dispid;   // DISPID of method/property
    void (__stdcall T::*pfn)(); // method to invoke
    _ATL_FUNC_INFO* pInfo; // pointer to info structure
};

When you use the BEGIN_SINK_MAP macro, you define a static member function in your class called _GetSinkMap. It returns the address of the array of _ATL_EVENT_ENTRY structures.

#define BEGIN_SINK_MAP(_class)\
    typedef _class _GetSinkMapFinder;\
    static const ATL::_ATL_EVENT_ENTRY<_class>* _GetSinkMap() {\
        PTM_WARNING_DISABLE \
        typedef _class _atl_event_classtype;\
        static const ATL::_ATL_EVENT_ENTRY<_class> map[] = {

Each SINK_ENTRY_INFO macro adds one _ATL_EVENT_ENTRY structure to the array.

#define SINK_ENTRY_INFO(id, iid, dispid, fn, info) {id, &iid,
  (int)(INT_PTR)(static_cast<ATL::_IDispEventLocator<
    id, &iid>*>((_atl_event_classtype*)8))-8,
  dispid, (void (__stdcall _atl_event_classtype::*)())fn, info},

Two aspects of the macro are a little unusual. The following expression computes the offset of the _IDispEventLocator<id, &iid> base class with respect to your deriving class (the class containing the sink map). This enables us to find the appropriate event sink referenced by the sink map entry.

(int)(INT_PTR)(static_cast<_IDispEventLocator<
    id, &iid>*>((_atl_event_classtype*)8))-8

The following cast saves the event-handler function address as a pointer to a member function:

(void (__stdcall _atl_event_classtype::*)()) fn

The SINK_ENTRY_EX macro is the same as the SINK_ENTRY_INFO macro with a NULL pointer for the function information structure. The SINK_ENTRY macro is thesame as the SINK_ENTRY_INFO macro with IID_NULL for the dispatch interface and a NULL pointer for the function information structure.

#define SINK_ENTRY_EX(id, iid, dispid, fn) \
  SINK_ENTRY_INFO(id, iid, dispid, fn, NULL)
#define SINK_ENTRY(id, dispid, fn) \
  SINK_ENTRY_EX(id, IID_NULL, dispid, fn)

The END_SINK_MAP macro ends the array and completes the _GetSinkMap function implementation:

#define END_SINK_MAP() {0, NULL, 0, 0, NULL, NULL} }; \
  return map;\

The IDispEventImpl Class

Finally, we come to the IDispEventImpl class. This is the class that the code-generation wizards use. It derives from the IDispEventSimpleImpl class and, therefore, inherits all the functionality previously discussed. The additional template parameters specify a type library that describes the source dispatch interface for the event sink.

template <UINT nID, class T, const IID* pdiid = &IID_NULL,
  const GUID* plibid = &GUID_NULL,
  WORD wMajor = 0, WORD wMinor = 0,
  class tihclass = CComTypeInfoHolder>
class ATL_NO_VTABLE IDispEventImpl :
  public IDispEventSimpleImpl<nID, T, pdiid>
{ ... }

The main feature of the IDispEventImpl class is that it uses the type information to implement functionality that is missing in the base class. The class implements the GetTypeInfoCount, GetTypeInfo, and GetIDsOfNames methods using the type library via a CComTypeInfoHolder object:

STDMETHOD(GetTypeInfoCount)(UINT* pctinfo) {
  *pctinfo = 1; return S_OK; }
STDMETHOD(GetTypeInfo)(UINT itinfo, LCID lcid, ITypeInfo** pptinfo)
{ return _tih.GetTypeInfo(itinfo, lcid, pptinfo); }
STDMETHOD(GetIDsOfNames)(REFIID riid, LPOLESTR* rgszNames,
  UINT cNames, LCID lcid, DISPID* rgdispid) {
    return _tih.GetIDsOfNames(riid, rgszNames, cNames,
      lcid, rgdispid);
}

It also overrides the GetFuncInfoFromId method and initializes an _ATL_FUNC_INFO structure using the information provided in the type library:

HRESULT GetFuncInfoFromId(const IID& iid,
    DISPID dispidMember, LCID lcid,
    ATL_FUNC_INFO& info) {
    CComPtr<ITypeInfo> spTypeInfo;

    if (InlineIsEqualGUID(*_tih.m_plibid, GUID_NULL))
    {
        m_InnerLibid = m_libid;
        m_InnerIid = m_iid;
        _tih.m_plibid = &m_InnerLibid;
        _tih.m_pguid = &m_InnerIid;
        _tih.m_wMajor = m_wMajorVerNum;
        _tih.m_wMinor = m_wMinorVerNum;
    }
    HRESULT hr = _tih.GetTI(lcid, &spTypeInfo);
    if (FAILED(hr))
        return hr;
    return AtlGetFuncInfoFromId(spTypeInfo, iid,
        dispidMember, lcid, info);
}

Summary

The connection point protocol defines a mechanism for a client interested in receiving event callbacks to pass its event sink interface pointer to an event source. Neither the client nor the event source needs to be written with knowledge of each other. Objects hosted on a web page or, more generally, objects used by scripting languages must use the connection points protocol to fire events to the scripting engine. Also, ActiveX controls fire their events using the connection points protocol. Although this protocol is acceptable for intra-apartment use, it is inefficient (when considering round-trips) for use across an apartment boundary.

ATL provides the IDispEvent and IDispEventSimple classes for a client object to use to receive event callbacks. Additionally, ATL provides the Implement Connection Point Wizard so you can easily generate a class that manages a connection point and contains helper methods to fire the events to all connected clients.