An introduction to MFC's COM Interface Macros

Introduction

As part of a project I'm working on I need to implement multiple COM interfaces.

If I wanted to implement the IWidget interface and the IThingAMaBob interface it might look like this.

class CWidgets : public IWidgets
{
public:
    virtual HRESULT __stdcall QueryInterface(REFIID riid, 
                                     void __RPC_FAR *__RPC_FAR *ppvObject);
    virtual ULONG   __stdcall AddRef(void);
    virtual ULONG   __stdcall Release(void);

    virtual HRESULT __stdcall MyExtraFunction();
};

and similarly for the IThingAMaBob interface. This is COM 101 material.

It becomes a bit tedious coding this all the time. Factor in the need to implement, for each interface, the IUnknown base methods correctly (especially QueryInterface) and the smart programmer starts researching better (easier) ways to do it.

Fortunately, for the MFC programmer, MFC provides a much easier way to not only implement a COM interface, it provides an easy way to define multple interfaces in the one class.

MFC COM Macros

We can rewrite our CWidgets class like this, using some MFC macros.

class CWidgets : public CCmdTarget
{
public:
    DECLARE_INTERFACE_MAP()

    BEGIN_INTERFACE_PART(Widgets, IWidgets)
        STDMETHOD(MyExtraFunction)();
    END_INTERFACE_PART(Widgets)
};

The first thing you'll notice is that the class is now derived from CCmdTarget. It needs to be derived from CCmdTarget either directly or indirectly for reasons we'll see a little later. The class then declares an interface map followed by an interface part. The interface part defines a nested class called (in this case) XWidgets which is derived from the IWidgets interface. (The macro prepends an X to the first parameter of the macro to give the nested class a unique name that won't clash with the 'C' or 'I' names). The BEGIN_INTERFACE_PART macro also declares the 3 standard methods inherited from IUnknown for us. Any additional methods for this interface must be defined between the BEGIN_INTERFACE_PART and END_INTERFACE_PART macros.

In our implementation file we'd have something like this.

BEGIN_INTERFACE_MAP(CWidgets, CCmdTarget)
    INTERFACE_PART(CWidgets, IID_IWidgets, Widgets)
END_INTERFACE_MAP()

plus our implementation of the methods of the IWidgets interface. Note that even though we don't have to declare the basic IUnknown methods we do have to implement them. The four methods of our IWidgets interface might look like this.

STDMETHODIMP_(ULONG) CWidgets::XWidgets::AddRef()
{
    METHOD_PROLOGUE(CWidgets, Widgets);
    
    return pThis->ExternalAddRef();
}

STDMETHODIMP_(ULONG) CWidgets::XWidgets::Release()
{
    METHOD_PROLOGUE(CWidgets, Widgets)

    return pThis->ExternalRelease();
}

STDMETHODIMP CWidgets::XWidgets::QueryInterface(REFIID iid, LPVOID far* ppvObj)     
{
    METHOD_PROLOGUE(CWidgets, Widgets)

    return pThis->ExternalQueryInterface(&iid, ppvObj);
}

STDMETHODIMP CWidgets::XWidgets::MyExtraFunction()
{
    METHOD_PROLOGUE(CWidgets, Widgets)

    //  Do something

    .
    .
    .
    
    return S_OK;
}

Before we dive into this let's recap. Our class is derived from CCmdTarget and, via the BEGIN_INTERFACE_PART macro, contains a nested class called XWidgets.

The first thing you'll notice in the nested class implementation is a new macro, METHOD_PROLOGUE. It takes two arguments. The first is the name of the enclosing class, the second is the name of the inner class (without the X). If we look at the definition of the macro we see this

#define METHOD_PROLOGUE(theClass, localClass) \
    theClass* pThis = \
        ((theClass*)((BYTE*)this - offsetof(theClass, m_x##localClass))); \
    AFX_MANAGE_STATE(pThis->m_pModuleState) \
    pThis; // avoid warning from compiler \

which the preprocessor replaces with

    CWidgets* pThis = \
        ((CWidgets*)((BYTE*)this - offsetof(CWidgets, m_xWidgets:))); \
    AFX_MANAGE_STATE(pThis->m_pModuleState) \
    pThis; // avoid warning from compiler \

which declares a pointer called pThis of type CWidgets and initialises it to point at the enclosing CWidgets class. It does this via some pointer arithmetic using the this pointer and m_xWidgets. Ignore, for now, how m_xWidgets got there, simply accept that it's an embedded instance of the XWidgets class.

Once we've got a pointer to the enclosing class we can access data in the enclosing class or call member functions on the enclosing class. This is where the derivation from CCmdTarget comes into play.

MFC provides us with an implementation of AddRef() and Release() which we can access via pThis. Hence the calls to ExternalAddRef() etc. ExternalAddRef() either calls our external IUnknown if our interface is aggregrated, or it increments a reference counter in our base CCmdTarget object. Since I'm not concerned in this article with aggregration that's the last mention you'll see of the subject. Similarly, calling ExternalRelease() decrements our reference count.

More importantly, MFC gives us a correct implementation of QueryInterface(). By correct I mean that it follows the semantics of QueryInterface. If you have an IWidgets interface you can use it to obtain an IUnknown interface. Or vice versa. Which is, of course, the way it's supposed to work but a surprisingly high number of programmers (myself included) sometimes forget to implement the query for IUnknown.

Instances of nested classes

Once we've defined our interface and written the implementation we need to have an instance of the class to use. One might be tempted to do this in our outer class.

class CWidgets : public CCmdTarget
{
public:
    DECLARE_INTERFACE_MAP()

    BEGIN_INTERFACE_PART(Widgets, IWidgets)
        STDMETHOD(MyExtraFunction)();
    END_INTERFACE_PART(Widgets)
    
    XWidgets    m_myWidget;
};

which defines the XWidgets class and then creates an instance of it embedded in the CWidgets object. That'll certainly compile but when your client code calls QueryInterface() to get an instance of the XWidgets class it won't get a pointer to m_myWidget. What it gets is a pointer to an instance of XWidgets called m_xWidgets. Hang on! Where did m_xWidgets come from?

Hidden inside the END_INTERFACE_PART macro is a declaration of an instance of the nested class. Note this well. Usually when you define a nested class you have to declare an instance of the nested class within the enclosing class. The MFC macros assume that you'll always have an embedded instance of the nested class in the enclosing object, so it creates one for you, naming the instance by prepending m_x to the nested class name.

Steak knives anyone?

So far so good. But wait, there's more! The macros also make it very easy to implement multiple interfaces in the one object. Let's expand our class a little to incorporate an implementation of the IThingAMaBob interface. Of course, it only makes sense to combine the two interfaces in the one object if a Widget and a ThingAMaBob are related so let's assume they are. Our class would now look like this.

class CWidgets : public CCmdTarget
{
public:
    DECLARE_INTERFACE_MAP()

    BEGIN_INTERFACE_PART(Widgets, IWidgets)
        STDMETHOD(MyExtraFunction)();
    END_INTERFACE_PART(Widgets)
    
    BEGIN_INTERFACE_PART(ThingAMaBob, IThingAMaBob)
        STDMETHOD(SomeOtherFunction)();
    END_INTERFACE_PART(ThingAMaBob)
};

which defines a second nested class called XThingAMaBob. In our implementation file the interface map now looks like this.

BEGIN_INTERFACE_MAP(CWidgets, CCmdTarget)
    INTERFACE_PART(CWidgets, IID_IWidgets, Widgets)
    INTERFACE_PART(CWidgets, IID_IThingAMaBob, ThingAMaBob)
END_INTERFACE_MAP()

and we'd add whatever methods are part of the XThingAMaBob class (not forgetting the IUnknown methods). As part of all this we get a new member variable in the containing class called m_xThingAMaBob of type XThingAMaBob.

The really nice thing about this is that if QueryInterface() in your implementation calls pThis->ExternalQueryInterface() you'll automatically find and return the embedded m_xSomething instance associated with the iid you (or some other program) requested, with all the plumbing taken care of by the interface map and CCmdTarget. You don't have to write a bunch of code in each objects QueryInterface() method to make it aware of the other interfaces implemented on the containing object. More importantly, if you add an interface to the class, all you have to remember is to add it to the interface map in the implementation file and MFC will take care of the rest.

Reference Counting

Because the interfaces are defined within an MFC object they have the same lifetime as the enclosing object. Thus, as you've already seen, it's possible to do reference counting in the enclosing object rather than make each interface responsible for it's own counting. All interfaces implemented on the class share a single reference counter. In debug builds MFC does an ASSERT(dwRef <= 1) on the reference counter during the CCmdTarget::~CCmdTarget() destructor. If you encounter that assert it means that someone somewhere hasn't done a Release() on one or more of your interface pointers.

Variables, methods and constructors in the nested class

As well as defining COM methods for a nested class it's possible to embed normal (non COM) methods, constructors and destructors and member variables inside a nested class. All you have to do is add them between the BEGIN_INTERFACE_PART and END_INTERFACE_PART macros. The only 'special' thing you have to remember is that the constructor / destructor names are the classname with an 'X' prepended.

class CWidgets : public CCmdTarget
{
public:
    DECLARE_INTERFACE_MAP()

    BEGIN_INTERFACE_PART(Widgets, IWidgets)
        STDMETHOD(MyExtraFunction)();
    END_INTERFACE_PART(Widgets)
    
    BEGIN_INTERFACE_PART(ThingAMaBob, IThingAMaBob)
        STDMETHOD(SomeOtherFunction)();
        
        XThingAMaBob();
        ~XThingAMaBob();
        
    private:
        BOOL    m_bMyBool;
    END_INTERFACE_PART(ThingAMaBob)
};

Which defines a constructor / destructor pair called XThingAMaBob and a private BOOL variable called m_bMyBool. Within your nested class code you access members defined this way just as you would in a non nested class, via the implicit this pointer.

History

16 April 2004 - Initial version.