Sinking connection points in C++ objects

The following source was built using Visual Studio 6.0 SP5 and Visual Studio .Net. You need to have the Microsoft NetMeeting SDK installed. This is available from here or as part of recent versions of the Microsoft Platform SDK.

• Download source files - 74 Kb

Sinking connection points in C++ objects.

Many COM objects provide events to their clients by means on Connection Points. A Connection Point is a generalised method of allowing clients to register a COM interface so that the object can notify them of things that they may be interested in. The problem is, sometimes you will be developing code that simply uses COM objects and doesn't implement any COM objects itself, yet you still need to be able to register a COM object to receive notifications via a Connection Point. This article shows you how you can use Connection Points and sink events from them without needing to use ATL or MFC or expose real COM objects from your application.

Registering for notifications

Suppose we want to use a COM object that provides notifications via Connection Points, the NetMeeting Conference Manager object for example. Our application will create an instance of the Conference Manager object and manipulate it via its interface, we will monitor the events it generates by registering a connection point to receive events generated by the INmManagerNotify interface. The INmManagerNotify interface is shown below:

   interface INmManagerNotify : IUnknown
   {
      typedef [unique] INmManagerNotify *LPNMMANAGERNOTIFY;
 
      HRESULT NmUI(
         [in] CONFN uNotify);

      HRESULT ConferenceCreated(
         [in] INmConference *pConference);

      HRESULT CallCreated(
         [in] INmCall *pCall);
   }

We don't want to use MFC or ATL and the resulting program will be a console application using straight C++ and COM client APIs. Our problem is that our application simply uses COM, it doesn't expose any COM functionality itself and we don't want to add the complexity of being able to serve real COM objects simply so that we can consume events from a Connection Point. What we'd like to do is simply implement the methods of the notification interface and ask the Conference Manager object to call us when notifications occur without worrying about the necessary plumbing.

A reusable, self contained, notification class

The work involved to hook up a connection point is fairly straight forward and MFC and ATL could both provide some help if we were using them, but since we're not we have to do the work ourselves. Given the IUnknown of a connectable object we need to obtain a pointer to its IConnectionPointContainer interface and from that obtain a pointer to the required connection point interface. Once we have that, we simply call the Advise() member function, pass our sink interface and keep hold of the cookie that is returned as we need it to disconnect. If we wrap this work in a class we can make sure that we disconnect in the destructor. The class might look something like this:

   class CNotify 
   {
      public :

         CNotify();
         ~CNotify();
	   
         void Connect(
            IUnknown *pConnectTo, 
            REFIID riid, 
            IUnknown *pIUnknown);

         void Disconnect();

         bool Connected() const;

         private :

            DWORD m_dwCookie;
            IUnknown *m_pIUnknown;
            IConnectionPoint *m_pIConnectionPoint;
            IConnectionPointContainer *m_pIConnectionPointContainer;
   };

Connecting can be as simple as calling Connect() and passing the connectable object, the IID of the connection point that we wish to connect to and our sink interface. Disconnecting is equally easy.

The class above is useful but it doesn't solve our problem. We still need to have a COM object to pass as our sink interface and we don't have one, or want to build one. However, it's relative easy to put together a template class that's derived from our CNotify class and fills in the missing functionality. The template looks something like this:

   template <class NotifyInterface, const GUID *InterfaceIID> class TNotify : 
      private CNotify, 
      public NotifyInterface
   {
      public :

         void Connect(IUnknown *pConnectTo)
         {
            CNotify::Connect(pConnectTo, *InterfaceIID, this);
         }

         using CNotify::Disconnect;
         using CNotify::Connected;

         // IUnknown methods

         ULONG STDMETHODCALLTYPE AddRef()
         {
            return 2;
         }

         ULONG STDMETHODCALLTYPE Release()
         {
            return 1;
         }

         HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, PVOID *ppvObj)
         {
            HRESULT hr = S_OK;

            if (riid == IID_IUnknown)
            {
               *ppvObj = (IUnknown *)this;
            }
            else if (riid == *InterfaceIID)
            {
               *ppvObj = (NotifyInterface *)this;
            }
            else
            {
               hr = E_NOINTERFACE;
               *ppvObj = NULL;
            }

            return hr;
        }
   };

TNotify is used as a base class for your notification sink object, it derives from the sink interface that you want to implement and provides the IUnknown methods for you. You simply have to implement the sink interface methods and then call Connect() and pass the connectable object that you wish to connect to. Your sink object might look like this:

   class MyConferenceManager : private TNotify
   {
      public :

         HRESULT STDMETHODCALLTYPE NmUI(CONFN confn)
         {
            return S_OK;
         }

         HRESULT STDMETHODCALLTYPE ConferenceCreated(INmConference *pConference)
         {
            return S_OK;
         }

         HRESULT STDMETHODCALLTYPE CallCreated(INmCall *pCall)
         {
            return S_OK;
         }
   };

You need to be aware of a few things when using your sink object. The first is that the COM object that is constructed for you by the TNotify base class expects to reside on the stack, or, at least, it doesn't expect COM to manage its lifetime (notice the implementation of AddRef() and Release()). Secondly the sink object maintains references to the connectable object's interfaces, so that it can disconnect when you call Disconnect() or, if you don't, when it gets destroyed. Finally, since the sink object could make COM calls when it is destroyed you need to make sure that COM is still initialised at that point - so no calling CoUninitialize() before you destroy your sink object.

The example code

The example code is slightly more complex than that shown above. Because of all the type mapping that you tend to have to do to call COM methods from straight C++ we tend to wrap the COM objects in thin C++ wrappers. We do this with the interface that we obtain for the INmManager object and we use the same wrapper to sink the events. This leaves us with a single C++ object that exposes both the INmManager interface which translates the argument types to C++ friendly types and throws exceptions on method failures, and also exposes the INmManagerNotify interface to notify us of events that occur on the object. As you'll see, creating and using the NetMeeting Conference Manager COM object and wiring it up to receieve notification events is as simple this:

   class MyConferenceManager : public CNmConferenceManager
   {
      public :
   
         // implement some or all of the INmManagerNotify methods to do 

         // stuff when the notifications happen...

   };

...

   if (MyConferenceManager::IsNmInstalled())
   {
      MyConferenceManager confManager;

      ULONG options = NM_INIT_NORMAL;
      ULONG capabilities = NMCH_ALL;

      confManager.Initialize(options, capabilities);

... 

Since the CNmConferenceManager object implements all of the notification interface and just does nothing, i.e. it returns S_OK to all methods, our derived class can choose to simply override the notifications that it wants to handle. Creating our object initialises COM, so that COM remains initialised until our object is no more, creates the NetMeeting Conference Manager COM object and connects up the notification sink. We can then simply call methods on the object and recieve notifications back.

Revision history

• 30th May 2002 - Initial revision.