December 1999

More Reusable MFC Goodies: Simplify Your (Programming) Life with the COMToys Library

Paul DiLascia

Reusable classes are like little COM tinkertoys you can assemble in different ways in different situations to create more elaborate objects. But how would you go about creating them? I used MyBands and the BandObj framework as a test bed to develop a library called COMToys.

This article assumes you're familiar with C++, COM, Internet Explorer

Code for this article: ComToys.exe (81KB)

Paul DiLascia is the author of Windows ++: Writing Reusable Code in C++ (Addison-Wesley, 1992) and a freelance consultant and writer-at-large. He can be reached at askpd@pobox.com or http://pobox.com/~askpd.

Last month I showed you a program called MyBands that enables you to put your own edit control in the Windows® task bar. MyBands implements three kinds of Windows band objects, among them the Web Search band shown in Figure 1. To implement MyBands, I wrote a mini band object framework, BandObj, with classes called CBandObjDll, CBandObjFactory, and CBandObj that provide all the support you need for writing any kind of band object with little effort.

Figure 1 The Web Search Band

CBandObj has lots of COM code to implement various interfaces like IDeskBand, IOleWindow, IContextMenu, and so on, but the only one that has anything to do with band objects is IDeskBand. The others are wholly generic. The CBandObj implementation for IContextMenu doesn't use anything from band objects; all it needs is a menu. All IOleWindow needs is a window handle. And so on for the others. It should be possible to extract these interface implementations and encapsulate them in reusable classes—little COM tinkertoys you can assemble in different ways in different situations to create more elaborate objects. But how exactly would you go about it?       This month, I'll show you how I used MyBands and the BandObj framework as a test bed to develop a library called COMToys. COMToys isn't an all-embracing system like the ActiveX® Template Library (ATL) or MFC; it's more of an ad hoc collection of macros, functions, classes, and whatever else I could think of to make writing BandObj easy. But COMToys offers an approach to programming COM in C++ that works for any kind of COM object, whether or not you're using MFC. More than anything else, COMToys is an attitude—one that says programming COM in C++ doesn't have to be hard. Really! COM: A C++ Programming Predicament       When it comes to COM, you have to pity the poor C++ programmer using the Java language and Visual Basic®. Programmers smile smugly as they write "form.color = red", while C++ hackers fret their instructions with QueryInterface and get_foo and set_mumble and—don't forget to check the HRESULT! Lord help you if you don't have a Release for every AddRef. In Visual Basic, you don't even have to type semicolons. C++ is far more powerful and leaner than Visual Basic and the Java language, but where COM is concerned, it seems hopelessly complex. How ironic when COM was designed for C++! After all, a COM object is just a C++ vtbl.       The problem isn't C++ and it isn't COM. The problem is that most C++ programmers don't know any better. They cut and paste from the SDK samples—long lines of open code that are intended only to demonstrate the rawest, most bare-bones way of doing something, without any thought toward system design. Folks, that stuff isn't production code! Why do you think they call it samples? C++ lets you program down to the metal—that's its advantage. But no one who isn't a masochist programs that way on a daily basis. If you want easy, you can have easy. You just have to take a little time up front to build some tools that'll repay you tenfold later. Visual Basic and the Java language are easy because have considerable infrastructure built in. But you can write your own infrastructure that makes C++ just as easy.       The MyBands program from last month has a two-layer architecture, with MyBands (the app) built on BandObj (the framework). This two-layer architecture is an artificial system I created for educational purposes. In reality, I built BandObj using the three-layered architecture shown in Figure 2, with COMToys providing the base. Only after the fact did I remove COMToys from the picture so that I could focus on band objects. Now it's time to reveal the whole system.

Figure 2 MyBands Architecture

As I was planning MyBands/BandObj/COMToys, I had to make a decision that confronts many programmers today: what programming system should I use to do COM? ATL? MFC? COM+ (whatever that is)? Or none of the above? I usually prefer to roll my own, but I have nothing against using someone else's wheel if it works and it's easy. So I considered both ATL and MFC.       ATL is lean and very clever, but who can read all those T's and angle brackets? Do you really know how much code ATL is generating? If the code is so generic that it fits in a template, why not use a simple class or subroutine instead? True, templates let you parameterize everything up the wazoo, which is cool. But all I want to do is drive to the grocery; I don't need or want a space shuttle for that. More important, ATL lacks the GUI support I want for shell extensions like band objects. On the up side, ATL's leanness, multiple inheritance model, and smart pointers are a big win, and you saw last month why the ATL registrar is the greatest thing since chocolate-covered espresso beans.       What about MFC? MFC has the GUI stuff in spades. Even if you don't need the doc/view architecture, there's all the command routing and ON_COMMAND_UPDATE_ UI handlers—essential stuff for any object with a UI. But when it comes to COM, MFC has its own infelicities. Most people worry about the elephantine DLL, but in my opinion that's a red herring. Yes, mfc42.dll is a sure candidate for the fat farm, but have you ever seen a Windows installation without it? For all practical purposes, mfc42.dll is part of the OS. (In fact, I just looked in my Windows 98 CAB and mfc42.dll is in win98_ 62.cab, so it is part of Windows—so what's to download?) When it comes to COM, MFC has an even bigger problem: its use of nested classes is downright demented. More on this shortly.       So which to use? In the end, I built my own system that uses both MFC and ATL. It saves me work, and dumps the parts of MFC and ATL that get in the way. COMToys uses the MFC class factories and IUnknown, but dumps nested classes. COMToys uses the ATL smart pointers, registrar, and multiple inheritance, but dumps the ponderous templates and confusing object model. This hybrid approach is not only practical, it's fun! (Plus, you always understand the code better when you write it yourself.)       I make no claim that COMToys is better than any other system; I simply offer it as something to think about. Mainly, I want to show that you don't have to use MFC, ATL, or any other system entirely. And how, by writing just a little infrastructure, you can make programming COM in C++ as easy as pie—even easier than Visual Basic! Gnarly Nested Classes       Enough with the punditry; let's look at some code. To explain how COMToys works, the first thing I have to do is show you one of the problems it is designed to overcome: the MFC use of nested classes. So let's take a quick MFC/COM 101 review.       To write a COM class in MFC, you derive your class from CCmdTarget and use macros to implement your interfaces. For example, if your class implements IPersistFile, you'd write:

 // in .h file
 class MyComClass : public CCmdTarget {
   BEGIN_INTERFACE_PART(PersistFile, IPersistFile)
   STDMETHODIMP GetClassID(LPCLSID pClsID);
   STDMETHODIMP IsDirty(void);
 •
 •
 •
   END_INTERFACE_PART(PersistFile)
 };

 // in .cpp file
 BEGIN_INTERFACE_MAP(CMyComClass, CCmdTarget)
   INTERFACE_PART(CMyComClass, IID_IPersistFile, PersistFile)
 •
 •
 •
 END_INTERFACE_MAP()

 { &IID_IPersistFile, offsetof(CMyComClass, m_xPersistFile) }

 // ditto for AdRef and Release
 STDMETHODIMP
 CMyComClass::XPersistFile::QueryInterface(...)
 {
   METHOD_PROLOGUE(CMyComClass, PersistFile)
   return pThis->ExternalQueryInterface(...);
 }

 class CMyComClass : 
   public IPersistFile,
   public IContextMenu, ...
 {
   // IUnknown
   STDMETHOD_(ULONG, AddRef)();
 •
 •
 •
 // IPersistFile
   STDMETHODIMP GetClassID(LPCLSID pClsID);
 •
 •
 •
 // IContextMenu 
   STDMETHOD (QueryContextMenu)(...);
 •
 •
 •
 };

Figure 3 Multiple Inheritance

If multiple inheritance is so great, why doesn't MFC use it? Because in the case of concrete classes—classes with real functions and data—multiple inheritance creates ambiguities. If you write x = m_foo, which m_foo do you mean, the one inherited from A or the one from B? And since MFC derives all its classes from CObject, using multiple inheritance would lead to the dreaded diamond hierarchy. You can use virtual base classes to overcome it, but things get messy real fast. So the founding fathers of MFC wisely decided to steer clear of multiple inheritance. Meet COMToys       Well, just because MFC is burdened by its tree-shaped object model doesn't mean COMToys has to be, right? In fact, COMToys uses multiple inheritance to do COM. To see how it works, let's look at CBandObj, the new version built with COMToys. To the outside world—that is, to apps like MyBands—CBandObj is exactly the same as before. Internally, things are different. First off, CBandObj is multiply derived from CWnd and IDeskBand.

 // in BandObj.h
 class CBandObj : 
   public CWnd, public IDeskBand 
 {
   DECLARE_IUnknown();
   // IDeskBand
   HRESULT GetBandInfo(...);
 •
 •
 •
 };

 // in BandObj.cpp
 IMPLEMENT_IUnknownCT(CBandObj);

 ULONG CBandObj::AddRef()
 {
   CMDTARGENTRYTR("CBandObj(%p)::AddRef, 
     count=%d\n", this, m_dwRef+1);
   return ExternalAddRef();
 }

 AFX_MANAGE_STATE(m_pModuleState);
 CTTRACEFN(...);

 // pseudo-code
 HRESULT 
 CCmdTarget::InternalQueryInterface
   (REFIID iid, void** ppv)
 {
   *ppv = GetInterfaceHook(iid);
   if (*ppv)
     return S_OK;
 // search interface maps
 •
 • 
 •
 }

 LPUNKNOWN CBandObj::GetInterfaceHook(void* piid)
 {
   REFIID iid = *((IID*)piid);
   if (iid==IID_IUnknown)
     return (IDeskBand*)this;
   if (iid==IID_IDeskBand) 
     return (IDeskBand*)this;
   return NULL;
 }

 HRESULT CBandObj::GetBandInfo(...)
 {
   // do it
 }

 class CBandObj : public CWnd, 
   // interfaces
 //public IOleWindow,     // inherited
 //public IDockingWindow, // inherited
   public IDeskBand,...
 
   // implementations
   public CTOleWindow,
   public CTDockingWindow,...
 {
   DECLARE_IUnknown();
   DECLARE_IOleWindow();
   DECLARE_IDockingWindow();
   // IDeskBand
   STDMETHOD(GetBandInfo)
     (DWORD, DWORD, DESKBANDINFO*);
 •
 •
 •
 }

 // in BandObj.cpp
 IMPLEMENT_IUnknownCT(CBandObj); // as before
 IMPLEMENT_IOleWindow(CBandObj, CTOleWindow);
 IMPLEMENT_IDockingWindow(CBandObj, CTDockingWindow);

 // generated by IMPLEMENT_IOleWindow
 HRESULT CBandObj::GetWindow(HWND* pHwnd)
 {
   CMDTARGENTRYTR(
     _T("CBandObj(%p)::IOleWindow::GetWindow\n"), 
     this);      
   return CTOleWindow::GetWindow(pHwnd);
 }

 // in CBandObj::GetInterfaceHook
 if (iid==IID_IOleWindow)
   return (IOleWindow*)this;
 if (iid==IID_IDockingWindow)
   return (IDockingWindow*)this;

 // not derived from IOleWindow!
 class CTOleWindow {
 public:
   // same macro as main class
   DECLARE_IOleWindow();
 };

 IMPLEMENT_IPersist(CMyComClass, CTPersist);

 class CTPersist {
 public:
   const CLSID& m_clsid;
   CTPersist(const CLSID& clsid) : m_clsid(clsid) { }
   STDMETHODIMP GetClassID(LPCLSID pClassID) {
     return pClassID ? 
       (*pClassID=m_clsid, S_OK) : E_UNEXPECTED;
   }
 };

 // in COMToys.h
 class CTMfcContextMenu {
 public:
   CCmdTarget* m_pCmdTarget;
   CMenu& m_ctxMenu;
   CTMfcContextMenu(CCmdTarget* pTarg, CMenu& menu)
     : m_pCmdTarget(pTarg), m_ctxMenu(menu) { }
 •
 •
 •
 };
 // In BandObj.cppCBandObj::CBandObj(REFCLSID clsid) :
   CTMfcContextMenu(this, m_menu), ...
 {
 •
 •
 •
 }

Figure 6 CBandObj Context Menu

When the container calls IContextMenu::QueryContextMenu to get the menu items, CTMfcContextMenu fills the menu with your CMenu items as you'd expect, but not before it creates a CCmdUI object and routes it through your CCmdTarget so all your ON_UPDATE_COMMAND_UI handlers can tweak the menu. Likewise, when the container calls InvokeCommand, CTMfcContextMenu sends the command to your command target's ON_COMMAND handlers. CTMfcContextMenu even does prompt strings by looking for string resources with IDs that match your menu items. In short, CTMfcContextMenu converts COM-speak to MFC-speak. All you have to do is give it a CMenu and a command target (usually the COM class itself) and forget about it. All the command stuff happens as it would in a vanilla MFC app. You never need to implement IContextMenu again—just use COMToys. A Problem in Paradise       When I first implemented COMToys, I ran into a minor snag. What happens if two COM interfaces have methods with the same name and signature? It's rare, but it does happen. For example, IPersistStream and IPersistFile both have IsDirty. So if you write

 DECLARE_IPersistFile();
 DECLARE_IPersistStream();

 // IPersistFile — whole interface
 IMPLEMENT_IPersistFile(CMyClass,CTPersistFile);
 
 // IPersistStream — each fn separate
 // IMPLEMENT_IPersistStream_IsDirty();
 IMPLEMENT_IPersistStream_Load(CMyClass,CTPersistStream);
 IMPLEMENT_IPersistStream_Save(CMyClass,CTPersistStream);
 IMPLEMENT_IPersistStream_GetSizeMax(CMyClass,CTPersistStream);

 extern "C"
 STDAPI DllGetClassObject(REFCLSID rclsid, REFIID riid, 
                          LPVOID* ppv)
 {
   MFCENTRY;
   return CTModule::GetModule()->
     OnGetClassObject(rclsid, riid, ppv);
 }

Figure 7 Class Relations

To do factories, COMToys has CTFactory. Mimicking MFC, CTModule::OnRegisterServer calls a static function, CTFactory::OnRegisterAll, which calls CTFactory::OnRegister for each factory. When you create a CTFactory, one of the parameters you must specify is a resource ID. By default, CTFactory::OnRegister looks for a REGISTRY resource (RGS script) with the same ID and invokes the ATL registrar to run it. But first it calls another virtual function, OnInitRegistryVariables, to initialize common registrar variables like %CLSID% and %ClassName%. Figure 8 shows the full list; you can override OnInitRegistryVariables to add your own. All this is the same as it was last month, only now the code is abstracted out of band objects and into COMToys. The upshot is, to handle registration/unregistration, all you have to do is write a registry script and stick it in your resource file with the same ID as your COM class.

 IDR_MYCOMCLASS REGISTRY DISCARDABLE "MyComClass.rgs"

 // in InitInstance
 new CTBandObjFactory(MYGUID, 
   RUNTIME_CLASS(CMyComClass),
   IDR_MAINFRAME);

 #define DECLARE_SMARTPTR(ifacename) \
 typedef CComQIPtr<ifacename> SP##ifacename;

 DECLARE_SMARTPTR(IPersist);

Figure 9 Aaaaah!

For an in-depth description of ATL smart pointers, see Don Box's "The Active Template Library Makes Building Compact COM Objects a Joy" (MSJ, June 1997). Don's article also describes the rare situations where smart pointers can cause trouble. Multithreading COMToys was not written with every kind of COM object in mind, only shell extensions. It assumes single-threaded apartments (STA), where class members are automatically thread-safe and only globals need be protected. COMToys classes that have static members (globals) also have a critical section, g_mydata, that you should lock before accessing. COMToys has a little class called CTLockData to make it easy. The constructor locks the critical section and the destructor unlocks it, so all you have to do is write this:

 { // protected block of code
   CTLockData lock(g_mydata);
 // do your worst
 •
 •
 •
 }

 {EB0FE172-1A3A-11D0-89B3-00A0C90A90AC}

 DEBUG_BEGIN_INTERFACE_NAMES()
   DEBUG_INTERFACE_NAME(IDeskBand)
 DEBUG_END_INTERFACE_NAMES()

 AfxOleUnregisterClass(m_clsid, GetProgID());

Figure 11 Yikes! Where Did Everything Go?

This can't be; REGEDIT must be confused (stage one, denial). So I quit REGEDIT and reran it from the Start menu. Instead of REGEDIT, I got a little dialog box. "This program refers to a nonexistent link..." or some such message that just as blandly understated the enormity of my situation. Everything on my desktop was wiped out. Windows Explorer? Gone. Microsoft Internet Explorer? Gone. Every icon replaced with the generic I-don't-understand icon. I couldn't even start an MS-DOS window because that link was gone too. I almost threw the keyboard through my monitor (stage two, anger). I rebooted with fingers crossed. No luck. I was hosed. MFC had completely erased my registry. I stared dumb-eyed at the screen (depression), trying to remember when I'd made the last backup (acceptance).       Fortunately, I use a commercial program that automatically backs up my registry every day. But how to run it when the link was gone? In the end I was able to click Run from the Start menu, then run\command.com to get a shell. I went to the ConfigSafe directory and ran it to restore my registry to the previous day's configuration. Whew!       A couple of cardiac pills and some postmortem spelunking revealed the events that led to my system's near-death experience. Since band objects aren't insertable, they don't need a ProgID. The registry string for MyBands has no ProgID, so CTFactory::GetProgID naturally returned an empty CString. Empty, mind you, not NULL. I passed this empty string along to AfxOleUnregisterClass, which has the following lines:

 if (pszProgID != NULL)
   _AfxRecursiveRegDeleteKey(HKEY_CLASSES_ROOT, 
     (LPTSTR)pszProgID);

For related information see: Creating Custom Explorer Bars, Tool Bands, and Desk Bands at: http://msdn.microsoft.com/library/psdk/shellcc/shell/Bands.htm.   Also check http://msdn.microsoft.com for daily updates on developer programs, resources and events.

From the December 1999 issue of Microsoft Systems Journal.