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.
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;
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 :
};
...
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.
