Chapter 6. Interface Maps

Chapter 4, “Objects in ATL,” discussed how ATL implements IUnknown, but it covered only AddRef and Release completely. This chapter takes a look first at the requirements that COM makes on an object’s implementation of QueryInterface and then at how ATL supports those requirements while still providing flexibility and extensibility.

Recall: COM Identity

From a client perspective, the rules of AddRef and Release are fairly stringent. Unless the client is careful about their use, objects can go away before expected or can stay around too long. However, the object is allowed to implement AddRef and Release in any number of ways, depending on how it wants to manage its own lifetime – for example, as a heap-based, stack-based, or cached object.

On the other hand, QueryInterface is easy to get right on the client side. Any client can ask an object if it supports any other functionality with a simple call. However, clients expect certain relationships between the interfaces on a COM object. These expectations form the laws of COM identity.

The Laws of COM Identity

The laws of COM identity say the following things about how an object must expose its interfaces via QueryInterface:

A client must be capable of getting directly to any interface implemented by the object via QueryInterface.
An object’s interfaces must be static throughout its lifetime.
QueryInterface for IUnknown must always succeed and must always return the same pointer value.

Direct Access to All Interfaces

The COM Specification states that an implementation of QueryInterface must be “reflexive, symmetric, and transitive.” This means that, given an interface, a client must be capable of using an interface to get directly to any interface implemented on the object, including the interface the client is using to perform the query. These relationships are mandated to maintain an object’s identity in the face of multiple references to the same object. If these relationships are not upheld, a client could find itself with some code that doesn’t work just because it asked for the interfaces in the wrong order. With a properly implemented QueryInterface, query order does not matter.

Static Types

Each object can decide for itself whether it wants to expose an interface via QueryInterface, regardless of the class to which it belongs. However, after it has been asked and has answered either “Yes, I support that interface” or “No, I don’t support that interface,” it must stick to that answer. The reason for this is simple: After an object answers the query, it may never be asked again. For example, a client can pass a resultant interface pointer to another client, which never has to ask the object at all.

The potential for clients “talking among themselves” means that an object cannot use QueryInterface to make client-specific decisions – for example, those based on security constraints. The object also cannot use QueryInterface to make context decisions that could change during the life of an object, such as time of day. If a client caches an interface pointer returned when the context is favorable, it might not ask again when the context has changed.

An Object’s Apartment-Specific Identifier

The remoting layer of COM uses the pointer returned when querying for IUnknown as an object’s unique identifier in that apartment. Clients can also compare IUnknown* s as an identity test:

 bool AreEqualObjects(IUnknown* punk1, IUnknown* punk2) {
   if( punk1 == null && punk2 == null ) return true;
   if( !punk1 || !punk2 ) return false;
   IUnknown* punka = 0; punk1->QueryInterface(IID_IUnknown,
     (void**)&punka);
   IUnknown* punkb = 0; punk2->QueryInterface(IID_IUnknown,
     (void**)&punkb);
   bool b = (punka == punkb);
   punka->Release(); punkb->Release();
   return b;
 }

In fact, the ATL smart pointer classes have a method called IsEqualObject for performing just this comparison:

 STDMETHODIMP CBall::SetPlaySurface(IRollSurface* prsNew) {
   if( m_sprs.IsEqualObject(prsNew) ) return S_OK;
   ...
 }

However, although COM dictates that the pointer value of IUnknown must always be the same, it places no such restrictions on any other interface. This particular loophole leads to such techniques as tear-off interfaces, discussed further in this chapter.

Nothing Else

As long as these three laws are upheld, an implementation of QueryInterface can be developed using scenes from your most vivid fever dreams. Frankly, I doubt you’ll be able to come up with any techniques wackier than those already known, as I present during the rest of this chapter. However, if you do, ATL’s implementation of QueryInterface is fully extensible, as you’ll see.

Table-Driven QueryInterface

The Raw Interface Map

ATL’s implementation of QueryInterface is called InternalQueryInterface and is provided as a static member function of CComObjectRootBase (shown here with debugging extensions removed):

 static HRESULT WINAPI
 CComObjectRootBase::InternalQueryInterface(
   void*                     pThis,
   const _ATL_INTMAP_ENTRY*  pEntries,
   REFIID                    iid,
   void**                    ppvObject)
 {
     // First entry in the com map should be a simple map entry
     ATLASSERT(pEntries->pFunc == _ATL_SIMPLEMAPENTRY);
     HRESULT hRes = AtlInternalQueryInterface(pThis, pEntries,
         iid, ppvObject);
     return hRes;
 }

I show you the implementation of the internal function, AtlInternalQueryInterface, later. First, let’s discuss the ATL_INTMAP_ENTRY structure, an array of which is passed to InternalQueryInterface:

 struct _ATL_INTMAP_ENTRY {
     const IID* piid;       // the interface id (IID)
     DWORD_PTR dw;
     _ATL_CREATORARGFUNC* pFunc; //NULL:end, 1:offset, n:ptr
 };

Each entry provides a pointer to an interface identifier, a pointer to a function to retrieve the requested interface, and a user-defined parameter to pass to the function. Functions that fit into this table must have signatures defined by the _ATL_CREATORARGFUNC typedef:

 typedef HRESULT (WINAPI _ATL_CREATORARGFUNC)(
     void* pv,        // Object's this pointer
     REFIID riid,     // IID of requested interface
     LPVOID* ppv,     // Storage for returned interface pointer
     DWORD_PTR dw);   // dw from the interface map entry

The job of the interface map function is to take the object’s this pointer, the interface that the client is requesting, and the dw argument, and to return the appropriate interface pointer in the ppv argument. The function is free to do whatever it likes, within the laws of COM identity, to perform this magic. For example, the following function assumes that the dw member is the offset of the vptr from the this pointer – that is, this function assumes that we’re using multiple inheritance (MI) to implement the interface:

 HRESULT WINAPI _MI(void* pvThis, REFIID riid, LPVOID* ppv, DWORD dw) {
   *ppv = (BYTE*)pvThis + dw;
   reinterpret_cast<IUnknown*>(*ppv)->AddRef();
   return S_OK;
 }

To fill in the _ATL_INTMAP_ENTRY for use with this function, we need to be able to calculate the offset of a vptr from the base, preferably at compile time. To help with this chore, ATL provides an interesting macro:

 #define _ATL_PACKING 8
 #define offsetofclass(base, derived) \
    ((DWORD_PTR)(static_cast<base*>((derived*)_ATL_PACKING))- \
    _ATL_PACKING)

The offsetofclass macro makes it look like we’re asking the compiler to dereference a pointer with the value 8, which is not such a great value for a pointer. [1] Instead, we’re asking the compiler to imagine a pointer to an object and to calculate the difference between that and a member inside that object, such as a vptr associated with a specific base class. The offsetofclass macro performs the same offset calculation the compiler does whenever it needs to perform a static_cast to a base class. Using offsetofclass enables us to fill an entry in an interface map like this:

 class CBeachBall :
   public CComObjectRootEx<CComSingleThreadModel>,
   public ISphere,
   public IRollableObject,
   public IPlaything {
 public:
 const static _ATL_INTMAP_ENTRY* WINAPI
 _GetEntries() {
   static const _ATL_INTMAP_ENTRY _entries[] = {
   { &IID_IUnknown, offsetofclass(ISphere, CBeachBall),
     _ATL_SIMPLEMAPENTRY },
   { &IID_ISphere, offsetofclass(ISphere, CBeachBall), _MI },
   { &IID_IRollableObject, offsetofclass(IRollableObject,
     CBeachBall), _MI },
   { &IID_IPlaything, offsetofclass(IPlaything, CBeachBall),
     _MI },
   };
 return _entries;
 };

 HRESULT _InternalQueryInterface(REFIID iid, void** ppvObject)
 {
   return InternalQueryInterface(this, _GetEntries(), iid,
     ppvObject);
 }
 ...
 };

Besides the population of the interface map, you can see a couple interesting things in this code snippet. First, the _InternalQueryInterface function calls _GetEntries to retrieve the static interface map and forwards it to the InternalQueryInterface static member function in CComObjectRootBase. CComObject et al requires the _InternalQueryInterface function to implement QueryInterface.

Second, notice that IUnknown is the initial entry in the list and uses _ATL_SIMPLEMAPENTRY instead of _MI. As discussed in Chapter 4, “Objects in ATL,” the first entry is the one used for IUnknown and is required to be a simple entry. A simple entry is a special case that indicates that the interface is being exposed using multiple inheritance and that an offset is all that is needed to calculate the requested interface pointer. _ATL_SIMPLEMAPENTRY is a special value used in the pFunc field of the _ATL_INTMAP_ENTRY structure to indicate this case:

1 #define _ATL_SIMPLEMAPENTRY ((ATL::_ATL_CREATORARGFUNC*)1)

When AtlInternalQueryInterface encounters this special value, it knows how to perform the offset calculation just like the example function, _MI. Because _ATL_SIMPLEMAPENTRY completely replaces the need for a function that performs the offset calculation, ATL provides no interface map functions like _MI, although it provides others, as I discuss later.

Convenience Macros

You might enjoy writing the required _InternalQueryInterface and _GetEntries methods, as well as the GetUnknown method discussed in Chapter 4, but I do not. To write these functions and begin the static definition of the interface map, ATL provides BEGIN_COM_MAP:

 #define BEGIN_COM_MAP(x) public: \
     typedef x _ComMapClass; \
     ...
     IUnknown* _GetRawUnknown() { \
         ATLASSERT(_GetEntries()[0].pFunc == \
             _ATL_SIMPLEMAPENTRY); \
         return (IUnknown*)((INT_PTR)this+_GetEntries()->dw); \
     } \
     _ATL_DECLARE_GET_UNKNOWN(x) \
     HRESULT _InternalQueryInterface(REFIID iid, \
         void** ppvObject) { \
         return InternalQueryInterface(this, _GetEntries(), \
         iid, ppvObject); } \
     const static ATL::_ATL_INTMAP_ENTRY* WINAPI _GetEntries() { \
     static const ATL::_ATL_INTMAP_ENTRY _entries[] = { \
          DEBUG_QI_ENTRY(x)

To zero-terminate the interface map and round out the _GetEntries implementation, ATL provides END_COM_MAP:

 #define END_COM_MAP() \
     __if_exists(_GetAttrEntries) {{NULL, \
         (DWORD_PTR)_GetAttrEntries, _ChainAttr }, }\
     {NULL, 0, 0}}; return _entries;} \
     virtual ULONG STDMETHODCALLTYPE AddRef( void) = 0; \
     virtual ULONG STDMETHODCALLTYPE Release( void) = 0; \
     STDMETHOD(QueryInterface)(REFIID, void**) = 0;

END_COM_MAP also provides another set of pure virtual member function definitions for QueryInterface, AddRef, and Release. This makes calls to IUnknown member functions unambiguous while calling them in the member functions of your ATL-based classes. We discuss the _GetAttrEntries function later in this chapter when we examine how ATL attributes can be used to declare an object’s supported interfaces.

To populate each entry in the interface map, ATL provides a set of macros that begin with the COM_INTERFACE_ENTRY prefix. The simplest and most useful is COM_INTERFACE_ENTRY itself:

 #define COM_INTERFACE_ENTRY(x)\
     {&_ATL_IIDOF(x), \
     offsetofclass(x, _ComMapClass), \
     _ATL_SIMPLEMAPENTRY},

Notice the use of _ComMapClass as the name of the class associated with the static interface map. BEGIN_COM_MAP provides this type. The _ATL_IIDOF macro, on the other hand, is ATL’s way of turning an interface type name into the corresponding GUID. Based on the presence or absence of the _ATL_NO_UUIDOF symbol, ATL either uses the VC++-specific __uuidof operator [2] or uses the C preprocessor’s token-pasting operator:

 #ifndef _ATL_NO_UUIDOF
 #define_ATL_IIDOF(x)__uuidof(x)
 #else
 #define_ATL_IIDOF(x)IID_##x
 #endif

Using these macros, the interface map can be defined much more simply than in the previous example:

 class CBeachBall :
   public CComObjectRootEx<CBeachBall>,
   public ISphere,
   public IRollableObject,
   public IPlaything {
 public:
 BEGIN_COM_MAP(CBeachBall)
   COM_INTERFACE_ENTRY(ISphere)
   COM_INTERFACE_ENTRY(IRollableObject)
   COM_INTERFACE_ENTRY(IPlaything)
 END_COM_MAP()
 ...
 };

AtlInternalQueryInterface

Checking for IUnknown

InternalQueryInterface delegates to a global function, AtlInternalQueryInterface, to provide its implementation. Before walking the table of interface entries, AtlInternalQueryInterface checks the IID of the request. If IUnknown is requested, it pulls the first entry from the table and hands it back immediately, without walking the rest of the table. This is a welcome optimization, but it’s more than that: It’s absolutely necessary that IUnknown not be calculated by calling a function. Functions can fail and functions can return different values for the same interface identifier, both of which violate the laws of COM identity. The practical meaning for your classes is that the first entry must always be a simple one. Luckily, ATL is laden with assertions to this affect, so as long as you test your implementations at least once in debug mode before you ship them to your customers, you should be safe (on this note, anyway).

Walking the Table

At each entry in the table, a decision is made based on whether the piid member, a pointer to the interface identifier for that entry, is NULL. If it is not NULL, the IID of the entry is compared with the IID of the request. If a match is found, the function pFunc references are called and the result is returned to the client. If there is no match, the search advances to the next entry in the table.

On the other hand, if the piid member is NULL, no matter what the IID of the request is, the pFunc is called. If the result is S_OK, the result is returned to the client. Otherwise, the search continues with the next entry. This behavior is used for any of the COM_INTERFACE_ENTRY_XXX_BLIND macros, such as COM_INTERFACE_ENTRY_AGGREGATE_BLIND.

Implementation

The following is the implementation of AtlInternalQueryInterface:

 ATLINLINE ATLAPI AtlInternalQueryInterface(
     void* pThis,
     const _ATL_INTMAP_ENTRY* pEntries,
     REFIID iid,
     void** ppvObject)
 {
     ATLASSERT(pThis != NULL);
     ATLASSERT(pEntries!= NULL);

     if(pThis == NULL || pEntries == NULL)
         return E_INVALIDARG ;

     // First entry in the com map should be a simple map entry
     ATLASSERT(pEntries->pFunc == _ATL_SIMPLEMAPENTRY);
     if (ppvObject == NULL)
         return E_POINTER;
     *ppvObject = NULL;
     if (InlineIsEqualUnknown(iid)) { // use first interface
         IUnknown* pUnk=(IUnknown*)((INT_PTR)pThis+pEntries->dw);
         pUnk->AddRef();
         *ppvObject = pUnk;
         return S_OK;
     }
     while (pEntries->pFunc != NULL) {
         BOOL bBlind = (pEntries->piid == NULL);
         if (bBlind || InlineIsEqualGUID(*(pEntries->piid), iid)) {
             if (pEntries->pFunc == _ATL_SIMPLEMAPENTRY) { //offset
                 ATLASSERT(!bBlind);
                 IUnknown* pUnk = (IUnknown*)((INT_PTR)
                     pThis+pEntries->dw);
                 pUnk->AddRef();
                 *ppvObject = pUnk;
                 return S_OK;
             }
             else { //actual function call
                 HRESULT hRes = pEntries->pFunc(pThis,
                     iid, ppvObject, pEntries->dw);
                 if (hRes == S_OK || (!bBlind && FAILED(hRes)))
                     return hRes;
             }
         }
         pEntries++;
     }
     return E_NOINTERFACE;
 }

Multiple Inheritance

To support multiple inheritance (MI) of interfaces, ATL provides four separate interface entry macros. Two are for straight casts and two are for branching casts. A straight cast is a static_cast that the compiler needs no extra information to perform – that is, there are no ambiguities. On the other hand, a branching cast is used when a class has several base classes that all derive from the same base class themselves. Because a straight cast to the common base class would be ambiguous, the compiler needs the inheritance branch to follow to resolve the ambiguity.

Straight Casting

COM_INTERFACE_ENTRY and COM_INTERFACE_ENTRY_IID

As I mentioned, COM_INTERFACE_ENTRY is the one you’ll use most of the time. Its close cousin is COM_INTERFACE_ENTRY_IID:

#define COM_INTERFACE_ENTRY_IID(iid, x) \
  { &iid, offsetofclass(x, _ComMapClass), _ATL_SIMPLEMAPENTRY},

This macro enables you to specify the IID separately from the name of the interface. The classic use of this macro is to avoid ambiguity. Imagine that you’ve got two interfaces that derive from the same base interface:

interface IGlobe : ISphere {};
interface IPlanet : ISphere {};

If you’ve got a class that derives from both of these interfaces, the compiler won’t know which base class to cast to if you use COM_INTERFACE_ENTRY for ISphere:

class CDesktopGlobe :
  public CComObjectRootEx<CDesktopGlobe>,
  public IGlobe,
  public IPlanet {
public:
  ...
BEGIN_COM_MAP(CDesktopGlobe)
  COM_INTERFACE_ENTRY(ISphere) // ambiguous
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
  // ISphere methods
  ...
  // IGlobe methods
  ...
  // IPlanet methods
  ...
};

The problem is more easily seen when you look at the inheritance hierarchy in Figure 6.1.

Figure 6.1. CDesktopGlobe inheritance hierarchy

Figure6.1 shows two interfaces that CDesktopGlobe has inherited from more than once, IUnknown and ISphere. IUnknown is not a problem because ATL handles it specially by choosing the first entry in the interface map (as discussed earlier). ISphere is a problem, though, because there are two of them, IGlobe and IPlanet. Each base interface has a separate vptr that points to a separate vtbl. Even though we’ve got a shared implementation of all the methods of ISphere and, therefore, duplicate entries in both the IGlobe and the IPlanet vtbls, the compiler needs us to pick one. COM_INTERFACE_ENTRY_IID enables us to resolve this ambiguity:

class CDesktopGlobe :
  public CComObjectRootEx<CDesktopGlobe>,
  public IGlobe,
  public IPlanet {
public:
...
BEGIN_COM_MAP(CDesktopGlobe)
  COM_INTERFACE_ENTRY_IID(IID_ISphere, IGlobe) // unambiguous
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
...
};

In this case, because we have shared implementations of the ISphere methods in our implementation of IGlobe and IPlanet, it doesn’t really matter which one we hand out. Sometimes it matters very much. COM_INTERFACE_ENTRY_IID is often used when exposing multiple dual interfaces, each of which derives from IDispatch. Using IDispatchImpl, we provide base class implementations of IDispatch that are different based on the dual interface we’re implementing. In fact, any time you’ve got multiple implementations of the same interface in the base classes, you must decide which implementation is the “default.” Imagine another example of a base class interface implementation that has nothing to do with scripting:

template <typename Base> class ISphereImpl : public Base {...};

Using ISphereImpl looks like this:

class CDesktopGlobe :
  public CComObjectRootEx<CDesktopGlobe>,
  public ISphereImpl<IGlobe>,
  public ISphereImpl<IPlanet> {
public:
...
BEGIN_COM_MAP(CDesktopGlobe)
  COM_INTERFACE_ENTRY_IID(IID_ISphere, IGlobe) // Default ISphere
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
...
};

Here’s the problem: If the client queries for IGlobe (or ISphere) and calls ISphere methods, it gets different behavior than if it were to query for IPlanet and call ISphere methods. Now the client has just the kind of order-of-query problem that the laws of COM identity were built to prohibit. Multiple implementations of the same base interface clearly violate the spirit, if not the letter, of the laws of COM identity.

Branch Casting

COM_INTERFACE_ENTRY2 and COM_INTERFACE_ENTRY2_IID

Both COM_INTERFACE_ENTRY2 and COM_INTERFACE_ENTRY2_IID are simple entries meant for use with MI:

 #define COM_INTERFACE_ENTRY2(x, x2)\
   { &_ATL_IIDOF(x),\
     reinterpret_cast<DWORD_PTR>( \
       static_cast<x*>( \
         static_cast<x2*>( \
           reinterpret_cast<_ComMapClass*>(8))))-8, \
     _ATL_SIMPLEMAPENTRY},

 #define COM_INTERFACE_ENTRY2_IID(iid, x, x2)\
   { &iid,\
     reinterpret_cast<DWORD_PTR>( \
       static_cast<x*>( \
         static_cast<x2*>( \
           reinterpret_cast<_ComMapClass*>(8))))-8, \
     _ATL_SIMPLEMAPENTRY},

COM_INTERFACE_ENTRY2 is much like COM_INTERFACE_ENTRY_IID because it enables you to resolve the problem of multiple bases:

class CDesktopGlobe :
  public CComObjectRootEx<CDesktopGlobe>,
  public IGlobe,
  public IPlanet {
public:
...
BEGIN_COM_MAP(CDesktopGlobe)
  COM_INTERFACE_ENTRY2(ISphere, IGlobe) // Use the IGlobal branch
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
...
};

This macro performs its magic by enabling you to specify two things, the interface to expose (such as ISphere) and the branch of the inheritance hierarchy tofollow to get to the implementation of that interface (such as IGlobe). This macro is slightly different from COM_INTERFACE_ENTRY_IID, in that the interface is specified by name instead of by IID. If you want to be very explicit about both, use COM_INTERFACE_ENTRY2_IID:

class CDesktopGlobe :
  public CComObjectRootEx<CDesktopGlobe>,
  public IGlobe,
  public IPlanet {
public:
...
BEGIN_COM_MAP(CDesktopGlobe)
  COM_INTERFACE_ENTRY2_IID(&IID_ISphere, ISphere, IGlobe)
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
...
};

COM_INTERFACE_ENTRY2[_IID] provides no extra functionality beyond what COM_INTERFACE_ENTRY[_IID] provides, so I tend to always use the latter.

Handling Name Conflicts

One of the problems with MI is name collisions. Imagine the following interfaces:

interface ICowboy : IUnknown {
    HRESULT Draw();
};

interface IArtist : IUnknown {
   HRESULT Draw();
};

Because both Draw methods have the same signature, using straight MI requires a single shared implementation:

// Ace Powell was a cowboy/artist who lived in the western US
// from 1912 to his death in 1978. I'd like to thank Tim Ewald
// for this fabulous example, which I have used to death
// for years.
class CAcePowell :
    public CComObjectRootEx<CComSingleThreadModel>,
    public ICowboy,
    public IArtist
{
public:
BEGIN_COM_MAP(CAcePowell)
  COM_INTERFACE_ENTRY(ICowboy)
  COM_INTERFACE_ENTRY(IArtist)
END_COM_MAP()
...
  STDMETHODIMP Draw() { /* Act as a cowboy or an artist? */ }
};

The implied meaning of Draw is very different for an artist than it is for a cowboy, so we’d like to be able to provide two Draw implementations. We can deal with this predicament in a couple ways. The first solution uses a Microsoft-specific extension to the C++ language that allows a very intuitive syntax for disambiguating the Draw implementation. It’s employed as follows:

class CAcePowell :
    public CComObjectRootEx<CComSingleThreadModel>,
    public ICowboy,
    public IArtist {
public:
BEGIN_COM_MAP(CAcePowell)
  COM_INTERFACE_ENTRY(ICowboy)
  COM_INTERFACE_ENTRY(IArtist)
END_COM_MAP()
...
  STDMETHODIMP IArtist::Draw() {
    /* Draw like an artist */
    return S_OK;
  }

  STDMETHODIMP ICowboy::Draw() {
    /* Draw like a cowboy */
    return S_OK;
  }
};

By decorating the method with the name of the interface, the compiler can figure out which Draw method you are implementing. However, there is an important limitation with this technique imposed by what I consider a bug in the compiler: You must place the body of these methods in the class declaration in the header file. If you try to just put a declaration in the header file and put the body in the CPP file, it won’t compile.

This syntax is not Standard C++, so don’t expect to use this with non-Microsoft compilers (not that much of the rest of this book would be useful on non-Microsoft compilers anyway). If you’re implementing clashing methods from multiple interfaces, you might want to turn to alternative technique to address the problem of name collision. I call this technique, long known to the C++ community, forwarding shims. [3]

Forwarding shims rely upon the fact that although we can’t distinguish methods in the most derived class, we can certainly distinguish the methods in individual base classes:

struct _IArtist : public IArtist {
  STDMETHODIMP Draw() { return ArtistDraw(); }
  STDMETHOD(ArtistDraw)() =0;
};

struct _ICowboy : public ICowboy {
  STDMETHODIMP Draw() { return CowboyDraw(); }
  STDMETHOD(CowboyDraw)() =0;
};

Both _IArtist and _ICowboy are shim classes that implement the method with the conflicting name and forward to another pure virtual member function with a unique name. Because both shims derive from the interface in question, the interfaces IArtist and ICowboy can still appear in the interface map without difficulty:

class CAcePowell :
    public CComObjectRootEx<CComSingleThreadModel>,
    public _ICowboy,
    public _IArtist {
public:
BEGIN_COM_MAP(CAcePowell)
  COM_INTERFACE_ENTRY(ICowboy)
  COM_INTERFACE_ENTRY(IArtist)
END_COM_MAP()
...
  STDMETHODIMP ArtistDraw();
  STDMETHODIMP CowboyDraw();
};

This trick fills the vtbls for IArtist and ICowboy with _IArtist::Draw and _ICowboy::Draw. These functions, in turn, forward to the more derived class’s implementation of ArtistDraw and CowboyDraw. The forwarding shims remove the name conflict at the cost of an extra vtable per shim class, an extra entry per method per vtable, and an extra virtual function invocation per call. If this extra cost bothers you, remove it using the standard ATL tricks [4] :

template <typename Deriving>
struct ATL_NO_VTABLE _IArtist : public IArtist {
  STDMETHODIMP Draw() {
    return static_cast<Deriving*>(this)->ArtistDraw();
  }
};

template <typename Deriving>
struct ATL_NO_VTABLE _ICowboy : public ICowboy {
  STDMETHODIMP Draw() {
    return static_cast<Deriving*>(this)->CowboyDraw();
  }
};

class ATL_NO_VTABLE CAcePowell :
    public CComObjectRootEx<CComSingleThreadModel>,
    public _ICowboy<CAcePowell>,
    public _IArtist<CAcePowell>
{
public:
BEGIN_COM_MAP(CAcePowell)
  COM_INTERFACE_ENTRY(ICowboy)
  COM_INTERFACE_ENTRY(IArtist)
END_COM_MAP()
...
  HRESULT ArtistDraw();
  HRESULT CowboyDraw();
};

Don’t Go Off Half-Cocked…

You might think it would be enough to change one of the names by using only one forwarding shim:

template <typename Deriving>
struct ATL_NO_VTABLE _ICowboy : public ICowboy {
  STDMETHODIMP Draw() {
    return static_cast<Deriving*>(this)->CowboyDraw();
  }
};

class ATL_NO_VTABLE CAcePowell :
    public CComObjectRootEx<CComSingleThreadModel>,
    public _ICowboy<CAcePowell>,
    public IArtist {
public:
BEGIN_COM_MAP(CAcePowell)
  COM_INTERFACE_ENTRY(ICowboy)
  COM_INTERFACE_ENTRY(IArtist)
END_COM_MAP()
...
  HRESULT Draw();       // Use for both IArtist::Draw and
                        // ICowboy::Draw
  HRESULT CowboyDraw(); // Never called!
};

Don’t be tempted to try this. Remember that forwarding shims depend on overriding the behavior for the same member function name in the base classes. If you provide an implementation of the function in question with the same name as the function you’re implementing in the forwarding shim in the base, the forwarding shim function will never be called. By implementing one of the functions in the deriving class, you’ve effectively provided an implementation of both, putting you right back where you were in the first place.

Interface Coloring

In the same “sneaky C++ trick” way that forwarding shims let you fill the appropriate vtbl entries even if the compiler won’t cooperate, ATL supports another technique called interface coloring. Interface coloring is based on the idea that two classes can be layout compatible but not type compatible. Two classes are layout compatible if they have the same vtbl structure: The functions must be in exactly the same order, and the parameters must be exactly the same. The names, however, may be different. For example, the following two classes are layout compatible because they each result in a vtbl with the same number of methods, and every method at the same offset has the same signature:

struct ISphere : IUnknown {
  STDMETHOD(Rotate)(long nDegrees, long* pnOrientation) =0;
  STDMETHOD(Twirl)(long nVelocity) =0;
};

struct IRedSphere {
  // Colored IUnknown methods
  STDMETHOD(RedQueryInterface)( REFIID riid, void** ppv) =0;
  STDMETHOD_(ULONG, RedAddRef)() =0;
  STDMETHOD_(ULONG, RedRelease)() =0;

  // Uncolored ISphere methods
  STDMETHOD(Rotate)(long nDegrees, long* pnOrientation) =0;
  STDMETHOD(Twirl)(long nVelocity) =0;
};

However, because IRedSphere does not derive from ISphere, IRedSphere is not type compatible: The compiler won’t let you pass IRedSphere where ISphere is expected (without coercion). Cloning the layout of an interface is known as interface coloring. The layout-compatible interface is said to be colored because it is identical to the original, except for the names; that feature is not important to the runtime behavior of your object, just as a color is unimportant to the runtime behavior of your car. The names are used at compile time, though, and enable you to implement multiple versions of the same interface:

class CDesktopGlobe :
  public CComObjectRootEx<CComSingleThreadModel>,
  public IRedSphere,
  public IGlobe,
  public IPlanet {
public:
  ...
BEGIN_COM_MAP(CDesktopGlobe)
  // Expose IRedShere when ISphere is requested
  COM_INTERFACE_ENTRY_IID(IID_ISphere, IRedSphere)
  COM_INTERFACE_ENTRY(IGlobe)
  COM_INTERFACE_ENTRY(IPlanet)
END_COM_MAP()
  ...
  // Colored method implementations
  STDMETHODIMP RedQueryInterface(REFIID riid, void** ppv)
  { return GetUnknown()->QueryInterface(riid, ppv); }

  STDMETHODIMP_(ULONG) RedAddRef() {
    _ThreadModel::Increment(&m_cRefSphere);
    return GetUnknown()->AddRef();
  }

  STDMETHODIMP_(ULONG) RedRelease() {
    _ThreadModel::Decrement(&m_cRefSphere);
    return GetUnknown()->Release();
  }

private:
  long m_cRefSphere;
};

By deriving from IRedSphere, we can provide an implementation of all the colored methods separately from the uncolored ones. By coloring the IUnknown methods of IRedSphere, we can handle IUnknown calls on ISphere separately from the other implementations of IUnknown by the other interfaces. In this case, we’re using RedAddRef and RedRelease to keep track of an ISphere-specific reference count. And even though we expose IRedSphere to the client when it asks for ISphere, as far as the client is concerned, it has just an ISphere interface pointer. Because IRedSphere and ISphere are layout compatible, as far as COM is concerned, the client is right.

void TryRotate(IUnknown* punk) {
  ISphere* ps = 0;

  // Implicit AddRef really a call to RedAddRef
  if(SUCCEEDED(punk->QueryInterface(IID_ISphere, (void**)&ps))) {
    // ps actually points to an IRedSphere*

    ps->Rotate();
    ps->Release(); // Really a call to RedRelease
  }
}

COM_INTERFACE_ENTRY_IMPL and COM_INTERFACE_ENTRY_IMPL_IID

Interface coloring is somewhat interesting in the same way that a car wreck on the side of the road is interesting: It can be disconcerting as well and can slow traffic. Beginning with ATL 3.0, the vast majority of IXxxImpl classes no longer use interface coloring. In ATL 2. x, interface coloring was used for some, but not all, of the IXxxImpl classes to perform interface-specific reference counting. These implementation classes took the following form:

template <typename Deriving> class IXxxImpl {...};

Instead of deriving from the interface the class implemented, the implementation class used interface coloring to make itself layout compatible with the implemented interface. This enabled each class to implement its own reference counting but prohibited the use of the simple COM_INTERFACE_ENTRY macro. Additional macros were provided to make the necessary entries in the interface map:

#define COM_INTERFACE_ENTRY_IMPL(x) \
  COM_INTERFACE_ENTRY_IID(_ATL_IIDOF(x), x##Impl<_ComMapClass>)

#define COM_INTERFACE_ENTRY_IMPL_IID(iid, x) \
  COM_INTERFACE_ENTRY_IID(iid, x##Impl<_ComMapClass>)

The interface coloring technique was useful only if you wanted to track some of the ATL-implemented interfaces. Beginning with ATL 3.0, ATL uses a more generic mechanism [5] that tracks reference counts on all interfaces. Toward that end, all the ATL-implementation classes actually derive from the interface in question, making the use of COM_INTERFACE_ENTRY_IMPL and COM_INTERFACE_ENTRY_IMPL_IID macros unnecessary. All new and ported code should use COM_INTERFACE_ENTRY or COM_INTERFACE_ENTRY_IID instead. Old code that used the IMPL forms of the macros still compiles under the new ATL and acts appropriately.

Tear-Off Interfaces

Although multiple inheritance is preferred when implementing multiple interfaces, it’s not perfect. One of the problems is something called vptr-bloat. For each interface a class derives from, that’s another vptr per instance of that class. Beefing up our beach ball implementation can lead to some significant overhead:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything,
  public ILethalObject,
  public ITakeUpSpace,
  public IWishIWereMoreUseful,
  public ITryToBeHelpful,
  public IAmDepressed {...};

Because each beach ball implements eight interfaces, each instance has 32 bytes of overhead on Win32 systems before the reference count or any useful state. If clients actually made heavy use of these interfaces, that wouldn’t be too high of a price to pay. However, my guess is that most clients will use beach balls for their rollable and play-thing abilities. Because the other interfaces will be used infrequently, we’d rather not pay the overhead until they are used. For this, Crispin Goswell invented the tear-off interface, which he described in the article “The COM Programmer’s Cookbook.” [6]

Standard Tear-Offs

A tear-off interface is an interface that’d you want to expose on demand but not actually inherit from in the main class. Instead, an auxiliary class inherits from the interface to be torn off, and instances of that class are created any time a client queries for that interface. For example, assuming that few clients will think to turn a beach ball into a lethal weapon, ILethalObject would make an excellent tear-off interface for the CBeachBall class. Instead of using CComObjectRootEx as the base class, ATL classes implementing tear-off interfaces use the CComTearOffObjectBase as their base class:

template <class Owner, class ThreadModel = CComObjectThreadModel>
class CComTearOffObjectBase
    : public CComObjectRootEx<ThreadModel> {
public:
    typedef Owner _OwnerClass;
    Owner* m_pOwner;
    CComTearOffObjectBase() { m_pOwner = NULL; }
};

CComTearOffObjectBase provides one additional service, which is the caching of the owner of the tear-off interface. Each tear-off belongs to an owner object that has torn it off to satisfy a client’s request. The owner is useful so that the tear-off instance can access member data or member functions of the owner class:

class CBeachBallLethalness :
  public CComTearOffObjectBase<CBeachBall,
    CComSingleThreadModel>,
  public ILethalObject {
public:
BEGIN_COM_MAP(CBeachBallLethalness)
  COM_INTERFACE_ENTRY(ILethalObject)
END_COM_MAP()

  // ILethalObject methods
  STDMETHODIMP Kill() {
    m_pOwner->m_gasFill = GAS_HYDROGEN;
    m_pOwner->HoldNearOpenFlame();
    return S_OK;
  }
};

COM_INTERFACE_ENTRY_TEAR_OFF

To use this tear-off implementation, the owner class uses the COM_INTERFACE_ENTRY_TEAR_OFF macro:

#define COM_INTERFACE_ENTRY_TEAR_OFF(iid, x) \
  { &iid, \
    (DWORD_PTR)&ATL::_CComCreatorData< \
        ATL::CComInternalCreator< ATL::CComTearOffObject< x > > \
          >::data, \
  _Creator },

_CComCreatorData is just a sneaky trick to fill in the dw entry of the interface entry with a function pointer to the appropriate creator function. The creator function is provided by CComInternalCreator, which is identical to CComCreator except that it calls _InternalQueryInterface to get the initial interface instead of QueryInterface. This is necessary because, as I show you soon, QueryInterface on a tear-off instance forwards to the owner, but we want the initial interface on a new tear-off to come from the tear-off itself. That is, after all, why we’re creating the tear-off: to expose that interface.

The pFunc entry COM_INTERFACE_ENTRY_TEAR_OFF makes is the first instance of a nonsimple entry so far in this chapter and, thus, the first macro we’ve seen that cannot be used as the first entry in the interface map. The _Creator function is a static member of the CComObjectRootBase class that simply calls the Creator function pointer held in the dw parameter:

static HRESULT WINAPI
CComObjectRootBase::_Creator(void* pv, REFIID iid,
  void** ppv, DWORD_PTR dw) {
  _ATL_CREATORDATA* pcd = (_ATL_CREATORDATA*)dw;
  return pcd->pFunc(pv, iid, ppv);
}

The most derived class of a tear-off implementation is not CComObject, but rather CComTearOffObject. CComTearOffObject knows about the m_pOwner member of the base and fills it during construction. Because each tear-off instance is a separate C++ object, each maintains its own lifetime. However, to live up to the laws of COM identity, each tear-off forwards requests for new interfaces to the owner:

template <class Base>
class CComTearOffObject : public Base {
public:
    CComTearOffObject(void* pv) {
        ATLASSERT(m_pOwner == NULL);
        m_pOwner = reinterpret_cast<Base::_OwnerClass*>(pv);
        m_pOwner->AddRef();
    }

    ~CComTearOffObject() {
        m_dwRef = -(LONG_MAX/2);
        FinalRelease();
#ifdef _ATL_DEBUG_INTERFACES
        _AtlDebugInterfacesModule.DeleteNonAddRefThunk(
            _GetRawUnknown());
#endif
        m_pOwner->Release();
    }

    STDMETHOD_(ULONG, AddRef)() {
        return InternalAddRef();
    }

    STDMETHOD_(ULONG, Release)() {
        ULONG l = InternalRelease();
        if (l == 0)
            delete this;
        return l;
    }

    STDMETHOD(QueryInterface)(REFIID iid, void ** ppvObject) {
        return m_pOwner->QueryInterface(iid, ppvObject);
    }
};

To use a tear-off, the owner class adds an entry to its interface map:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything,
  //public ILethalObject, // Implemented by the tear-off
  public ITakeUpSpace,
  public IWishIWereMoreUseful,
  public ITryToBeHelpful,
  public IAmDepressed {
public:
BEGIN_COM_MAP(CBeachBall)
  COM_INTERFACE_ENTRY(ISphere)
  COM_INTERFACE_ENTRY(IRollableObject)
  COM_INTERFACE_ENTRY(IPlaything)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_ILethalObject,
    CBeachBallLethalness)
  COM_INTERFACE_ENTRY(ITakeUpSpace)
  COM_INTERFACE_ENTRY(IWishIWereMoreUseful)
  COM_INTERFACE_ENTRY(ITryToBeHelpful)
  COM_INTERFACE_ENTRY(IAmDepressed)
END_COM_MAP()
...
private:
  GAS_TYPE m_gasFill;
  void     HoldNearOpenFlame();
  // Tear-offs are generally friends
  friend class CBeachBallLethalness;
};

Because the owner class is no longer deriving from ILethalObject, each instance is 4 bytes lighter. However, when the client queries for ILethalObject, we’re spending 4 bytes for the ILethalObject vptr in CBeachBallLethalness, 4 bytes for the CBeachBallLethalness reference count, and 4 bytes for the m_pOwner back pointer. You might wonder how spending 12 bytes to save 4 bytes actually results in a savings. I’ll tell you: volume! Or rather, the lack thereof. Because we’re paying only the 12 bytes during the lifetime of the tear-off instance and we’ve used extensive profiling to determine ILethalObject is rarely used, the overall object footprint should be smaller.

Tear-Off Caveats

Before wrapping yourself in the perceived efficiency of tear-offs, you should be aware of these cautions:

Tear-offs are only for rarely used interfaces. Tear-off interfaces are an implementation trick to be used to reduce vptr bloat when extensive prototyping has revealed this to be a problem. If you don’t have this problem, save yourself the trouble and avoid tear-offs.
Tear-offs are for intra-apartment use only. The stub caches a tear-off interface for the life of an object. In fact, the current implementation of the stub manager caches each interface twice, sending the overhead of that particular interface from 12 bytes to 24 bytes.
Tear-offs should contain no state of their own. If a tear-off contains its own state, there will be one copy of that state per tear-off instance, breaking the spirit, if not the laws, of COM identity. If you have per-interface state, especially large state that you want to be released when no client is using the interface, use a cached tear-off.

Cached Tear-Offs

You might have noticed that every query for ILethalObject results in a new tear-off instance, even if the client already holds an ILethalObject interface pointer. This might be fine for a single interface tear-off, but what about a related group of interfaces that will be used together? [7] For example, imagine moving the other rarely used interfaces of CBeachBall to a single tear-off implementation:

class CBeachBallAttitude :
  public CComTearOffObjectBase<CBeachBall,
    CComSingleThreadModel>,
  public ITakeUpSpace,
  public IWishIWereMoreUseful,
  public ITryToBeHelpful,
  public IAmDepressed {
public:
BEGIN_COM_MAP(CBeachBallAttitude)
  COM_INTERFACE_ENTRY(ITakeUpSpace)
  COM_INTERFACE_ENTRY(IWishIWereMoreUseful)
  COM_INTERFACE_ENTRY(ITryToBeHelpful)
  COM_INTERFACE_ENTRY(IAmDepressed)
END_COM_MAP()
...
};

The following use of this tear-off implementation compiles and exhibits the appropriate behavior, but the overhead of even a single tear-off is exorbitant:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything
  // No tearoff interfaces in base class list
{
public:
BEGIN_COM_MAP(CBeachBall)
  COM_INTERFACE_ENTRY(ISphere)
  COM_INTERFACE_ENTRY(IRollableObject)
  COM_INTERFACE_ENTRY(IPlaything)
  // tearoffs are listed in the interface map
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_ILethalObject,
    CBeachBallLethalness)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_ITakeUpSpace,
    CBeachBallAttitude)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_IWishIWereMoreUseful,
    CBeachBallAttitude)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_ITryToBeHelpful,
    CBeachBallAttitude)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_IAmDepressed,
    CBeachBallAttitude)
END_COM_MAP()
...
};

Because we’ve grouped the “attitude” interfaces together into a single tear-off implementation, every time the client queries for any of them, it pays the overhead of all of them. To allow this kind of grouping but avoid the overhead of creating a new instance for every query, ATL provides an implementation of a cached tear-off. The owner holds a cached tear-off if there is even one outstanding interface to the tear-off. The initial query creates and caches the tear-off. Subsequent queries use the cached tear-off. The final release deletes the tear-off instance.

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF

To support caching tear-offs, ATL provides another interface macro:

#define COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk) \
  { &iid, \
    (DWORD_PTR)&ATL::_CComCacheData< \
    ATL::CComCreator< ATL::CComCachedTearOffObject< x > >, \
    (DWORD_PTR)offsetof(_ComMapClass, punk) >::data, \
    _Cache },

The _CComCacheData class is used to stuff a pointer into an _ATL_CACHEDATA structure:

struct _ATL_CACHEDATA {
  DWORD             dwOffsetVar;
  _ATL_CREATORFUNC* pFunc;
};

The use of this structure allows the dw to point to a Creator function pointer as well as another member, an offset. The offset is from the base of the owner class to the member data that is used to cache the pointer to the tear-off. The _Cache function, another static member function of CComObjectRootBase, uses the offset to calculate the address of the pointer and checks the pointer to determine whether to create a new instance of the cached tear-off:

static HRESULT WINAPI
CComObjectRootBase::_Cache(
    void* pv,
    REFIID iid,
    void** ppvObject,
    DWORD_PTR dw)
{
  HRESULT hRes = E_NOINTERFACE;
  _ATL_CACHEDATA* pcd = (_ATL_CACHEDATA*)dw;
  IUnknown** pp = (IUnknown**)((DWORD_PTR)pv + pcd->dwOffsetVar);
  if (*pp == NULL)
    hRes = pcd->pFunc(pv, __uuidof(IUnknown), (void**)pp);
  if (*pp != NULL)
    hRes = (*pp)->QueryInterface(iid, ppvObject);
  return hRes;
}

Just as an instance of a tear-off uses CComTearOffObject instead of CComObject to provide the implementation of IUnknown, cached tear-offs use CComCachedTearOffObject. CComCachedTearOffObject is nearly identical to CComAggObject [8] because of the way that the lifetime and identity of the tear-off are subsumed by that of the owner. The only difference is that the cached tear-off, like the tear-off, initializes the m_pOwner member.

Replacing the inefficient use of COM_INTERFACE_ENTRY_TEAR_OFF with COM_INTERFACE_ENTRY_CACHED_TEAR_OFF looks like this:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything {
public:
BEGIN_COM_MAP(CBeachBall)
  COM_INTERFACE_ENTRY(ISphere)
  COM_INTERFACE_ENTRY(IRollableObject)
  COM_INTERFACE_ENTRY(IPlaything)
  COM_INTERFACE_ENTRY_TEAR_OFF(IID_ILethalObject,
    CBeachBallLethalness)
  COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_ITakeUpSpace,
    CBeachBallAttitude, m_spunkAttitude.p)
  COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_IWishIWereMoreUseful,
    CBeachBallAttitude, m_spunkAttitude.p)
  COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_ITryToBeHelpful,
    CBeachBallAttitude, m_spunkAttitude.p)
  COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_IAmDepressed,
    CBeachBallAttitude, m_spunkAttitude.p)
END_COM_MAP()
DECLARE_GET_CONTROLLING_UNKNOWN() // See the Aggregation section
...
public:
  CComPtr<IUnknown> m_spunkAttitude;
};

Another Use for Cached Tear-Offs

Cached tear-offs have another use that is in direct opposition to standard tear-offs: caching per-interface resources. For example, imagine a dictionary object that implements a rarely used IHyphenation interface:

interface IHyphenation : public IUnknown {
  HRESULT Hyphenate([in] BSTR bstrUnhyphed,
    [out, retval] BSTR* pbstrHyphed);
};

Performing hyphenation is a matter of consulting a giant look-up table. If a CDictionary object were to implement the IHyphenation interface, it would likely doso as a cached tear-off to manage the resources associated with the look-up table. When the hyphenation cached tear-off is first created, it acquires the look-up table. Because the tear-off is cached, subsequent queries use the same look-up table. After all references to the IHyphenation interface are released, the look-up table can be released. If we had used a standard tear-off for this same functionality, a naïve implementation would have acquired the resources for the look-up table for each tear-off.

Aggregation: The Controlling Outer

As with tear-offs, aggregation enables you to separate the code for a single identity into multiple objects. However, whereas using tear-offs require shared source between the owner and the tear-off class, aggregation does not. The controlling outer and the controlling inner do not have to share the same server or even the same implementation language (although they do have to share the same apartment). If you like, you can consider an aggregated object a kind of “binary cached tear-off.” As with a cached tear-off, an aggregated instance’s lifetime and identity are subsumed by that of the controlling outer. Just like a cached tear-off, an aggregated instance must have a way to obtain the interface pointer of the controlling outer. In a tear-off, we pass the owner as a constructor argument. In aggregation, we do the same thing, but using the COM constructor that accepts a single, optional constructor argument – that is, the pUnkOuter parameter of IClassFactory::CreateInstance and its wrapper, CoCreateInstance:

interface IClassFactory : IUnknown {
HRESULT CreateInstance([in, unique]IUnknown* pUnkOuter,
[in] REFIID riid,
[out, iid_is(riid)] void **ppvObject);
HRESULT LockServer([in] BOOL fLock);
};

WINOLEAPI CoCreateInstance([in] REFCLSID rclsid,
[in, unique]LPUNKNOWN pUnkOuter,
[in] DWORD dwClsContext,
[in] REFIID riid,
[out, iid_is(riid)] LPVOID FAR* ppv);

In Chapter 4, “Objects in ATL,” I discussed how ATL supports aggregation as a controlled inner using CComAggObject (or CComPolyObject). In this chapter, I show you the four macros that ATL provides for the controlling outer in the aggregation relationship.

Manual Versus Automatic Creation

COM_INTERFACE_ENTRY_AGGREGATE and COM_INTERFACE_ENTRY_AGGREGATE_BLIND

ATL provides support for both planned and blind aggregation via the following two macros:

#define COM_INTERFACE_ENTRY_AGGREGATE(iid, punk) \
{ &iid, (DWORD_PTR)offsetof(_ComMapClass, punk), _Delegate },

#define COM_INTERFACE_ENTRY_AGGREGATE_BLIND(punk) \
{ NULL, (DWORD_PTR)offsetof(_ComMapClass, punk), _Delegate},

These macros assume that the aggregate has already been created manually and that the interface pointer is stored in the punk parameter to the macro. The _Delegate function forwards the QueryInterface request to that pointer:

static HRESULT WINAPI
CComObjectRootBase::

_Delegate(
void* pv,
REFIID iid,
void** ppvObject,
DWORD dw)
{
HRESULT hRes = E_NOINTERFACE;
IUnknown* p = *(IUnknown**)((DWORD_PTR)pv + dw);
if (p != NULL) hRes = p->QueryInterface(iid, ppvObject);
return hRes;
}

To use aggregation of an inner that has been manually created, the classes use COM_INTERFACE_ENTRY_AGGREGATE or COM_INTERFACE_ENTRY_AGGREGATE_BLIND in the interface map:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything {
public:
BEGIN_COM_MAP(CBeachBall)
  COM_INTERFACE_ENTRY(ISphere)
  COM_INTERFACE_ENTRY(IRollableObject)
  COM_INTERFACE_ENTRY(IPlaything)
COM_INTERFACE_ENTRY_AGGREGATE(IID_ILethalObject,
m_spunkLethalness)
COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_spunkAttitude)
END_COM_MAP()
DECLARE_GET_CONTROLLING_UNKNOWN()
DECLARE_PROTECT_FINAL_CONSTRUCT()
HRESULT FinalConstruct() {
HESULT hr;
hr = CoCreateInstance(CLSID_Lethalness,
GetControllingUnknown(),
CLSCTX_INPROC_SERVER,
IID_IUnknown,
(void**)&m_spunkLethalness);
if( SUCCEEDED(hr) ) {
hr = CoCreateInstance(CLSID_Attitude,
GetControllingUnknown(),
CLSCTX_INPROC_SERVER,
IID_IUnknown,
(void**)&m_spunkAttitude);
}
return hr;
}
void FinalRelease() {
m_spunkLethalness.Release();
m_spunkAttitude.Release();
}
...
public:
CComPtr<IUnknown> m_spunkLethalness;
CComPtr<IUnknown> m_spunkAttitude;
};

Notice that I have used the FinalConstruct method to create the aggregates so that failure stops the creation process. Notice also that because I’ve got a FinalConstruct that hands out interface pointers to the object being created, I’m using DECLARE_PROTECT_FINAL_CONSTRUCT to protect against premature destruction. I’ve also got a FinalRelease method to manually release the aggregate interface pointers to protect against double destruction. Aggregation was one of the chief motivations behind the multiphase construction of ATL-based COM objects, so it’s not surprising to see all the pieces used in this example.

However, one thing I’ve not yet mentioned is the DECLARE_GET_CONTROLLING_UNKNOWN macro. The controlling unknown is a pointer to the most controlling outer. Because aggregation can go arbitrarily deep, when aggregating, the outer needs to pass the pUnkOuter of the outermost object. To support this, ATL provides the GET_CONTROLLING_UNKNOWN macro to give an object the definition of a GetControllingUnknown function:

#define DECLARE_GET_CONTROLLING_UNKNOWN() public: \
virtual IUnknown* GetControllingUnknown() { \
return GetUnknown(); }

You might question the value of this function because it simply forwards to GetUnknown, but notice that it’s virtual. If the object is actually being created as an aggregate while it is aggregating, GetControllingUnknown is overridden in CComContainedObject:

template <class Base> class CComContainedObject : public Base {
...
IUnknown* GetControllingUnknown()
{ return m_pOuterUnknown; }
...
};

So, if the object is standalone, GetControllingUnknown returns the IUnknown* of the object, but if the object is itself being aggregated, GetControllingUnknown returns the IUnknown* of the outermost outer.

COM_INTERFACE_ENTRY_AUTOAGGREGATE and COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND

If you’re not doing any initialization of the aggregates, sometimes it seems a waste to create them until (or unless) they’re needed. For automatic creation of aggregates on demand, ATL provides the following two macros:

#define COM_INTERFACE_ENTRY_AUTOAGGREGATE(iid, punk, clsid) \
{ &iid, \
(DWORD_PTR)&ATL::_CComCacheData< \
ATL::CComAggregateCreator<_ComMapClass, &clsid>, \
(DWORD_PTR)offsetof(_ComMapClass, punk)>::data, \
_Cache },

#define COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(punk, clsid) \
{ NULL, \
(DWORD_PTR)&ATL::_CComCacheData< \
ATL::CComAggregateCreator<_ComMapClass, &clsid>, \
(DWORD_PTR)offsetof(_ComMapClass, punk)>::data, \
_Cache },

The only new thing in these macros is the CComAggregateCreator, which simply performs the CoCreateInstance the first time the interface is requested:

template <class T, const CLSID* pclsid>
class CComAggregateCreator {
public:
static HRESULT WINAPI CreateInstance(void* pv, REFIID,
LPVOID* ppv) {
T* p = (T*)pv;
return CoCreateInstance(*pclsid, p->GetControllingUnknown(),
CLSCTX_INPROC, __uuidof(IUnknown), ppv);
}
};

Using automatic creation simplifies the outer’s code somewhat:

class CBeachBall :
  public CComObjectRootEx<CBeachBall>,
  public ISphere,
  public IRollableObject,
  public IPlaything {
public:
BEGIN_COM_MAP(CBeachBall)
  COM_INTERFACE_ENTRY(ISphere)
  COM_INTERFACE_ENTRY(IRollableObject)
  COM_INTERFACE_ENTRY(IPlaything)
COM_INTERFACE_ENTRY_AUTOAGGREGATE(IID_ILethalObject,
m_spunkLethalness, CLSID_Lethalness)
COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(m_spunkAttitude,
CLSID_Attitude)
END_COM_MAP()

DECLARE_GET_CONTROLLING_UNKNOWN()

  void FinalRelease() {
    m_spunkLethalness.Release();
    m_spunkAttitude.Release();
  }
...
public:
  CComPtr<IUnknown> m_spunkLethalness;
  CComPtr<IUnknown> m_spunkAttitude;
};

Although we no longer need to perform the creation in FinalConstruct, we’re still required to use DECLARE_GET_CONTROLLING_UNKNOWN and to provide storage for the aggregated interfaces. We still release the interfaces manually in FinalRelease, as well, to avoid double destruction.

Aggregating the Free Threaded Marshaler

The ATL Object Wizard directly supports one particularly interesting use of aggregation: aggregating the implementation of IMarshal provided by the Free Threaded Marshaler (FTM). Any object that aggregates the FTM is said to be an apartment-neutral object. Normally, passing an interface pointer between apartments, even in the same process, results in a proxy-stub pair. The proxy-stub pair maintains the concurrency and synchronization requirements of both the object and the client, but it also adds overhead. In-process objects that provide their ownsynchronization and prefer to snuggle up to the client without the overhead of the proxy-stub can aggregate the FTM. By aggregating the FTM, an object short-circuits the creation of the proxy-stub for in-process objects. Therefore, the object can be passed between apartments in the same address space without the overhead of a proxy-stub.

The wizard generates the following code when the Free Threaded Marshaler option is checked in the ATL Object Wizard:

class ATL_NO_VTABLE CBowlingBall :
public CComObjectRootEx<CComMultiThreadModel>,
public CComCoClass<CBowlingBall, &CLSID_BowlingBall>,
public IBowlingBall
{
public:
CBowlingBall() { m_pUnkMarshaler = NULL; }

DECLARE_REGISTRY_RESOURCEID(IDR_BOWLINGBALL)
DECLARE_GET_CONTROLLING_UNKNOWN()
DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CBowlingBall)
COM_INTERFACE_ENTRY(IBowlingBall)
COM_INTERFACE_ENTRY_AGGREGATE(IID_IMarshal, m_pUnkMarshaler.p)
END_COM_MAP()

HRESULT FinalConstruct() {
return CoCreateFreeThreadedMarshaler(GetControllingUnknown(),
&m_pUnkMarshaler.p);
}
void FinalRelease() {
m_pUnkMarshaler.Release();
}

CComPtr<IUnknown> m_pUnkMarshaler;
...
};

Because the CLSID of the FTM is not available, instead of using auto-creation, ATL uses CoCreateFreeThreadMarshaler to create an instance of the FTM in the FinalConstruct method.

FTM Danger, Will Robinson! Danger! Danger!

Aggregating the FTM is easy, so I should mention a couple of big responsibilities that you, the developer, accept by aggregating the FTM:

Apartment-neutral objects must be thread safeYou can mark your class ThreadingModel=Apartment all day long, but because your object can be passed freely between apartments in the same process and, therefore, can used simultaneously by multiple threads, you’d better use CComMultiThreadModel and at least object-level locking. Fortunately, the ATL Object Wizard makes the FTM option available for selection only if you choose a threading model of Both or Neutral.
Apartment-neutral objects are not aggregatable. Aggregating the FTM depends on being able to implement IMarshal. If the outer decides to implement IMarshal and doesn’t ask the inner object, the inner can no longer be apartment neutral.
Apartment-neutral objects cannot cache interface pointers. An apartment-neutral object is said to be apartment neutral because it doesn’t care which apartment it is accessed from. However, other objects that an apartment-neutral object uses might or might not also be apartment-neutral. Interface pointers to objects that aren’t apartment neutral can be used only in the apartment to which they belong. If you’re lucky, the apartment-neutral object attempting to cache and use an interface pointer from another apartment will have a pointer to a proxy. Proxies know when they are being accessed outside their apartments and return RPC_E_WRONG_THREAD for all such method calls. If you’re not so lucky, the apartment-neutral object obtains a raw interface pointer. Imagine the poor single-threaded object accessed simultaneously from multiple apartments as part of its duty to the apartment-neutral object. It will most likely work just fine until you need to give a demo to your biggest client.

The only safe way to cache interface pointers in an apartment-neutral object is as cookies obtained from the Global Interface Table (GIT). The GIT is a process-global object provided to map apartment-specific interface pointers to apartment-neutral cookies and back. The GIT was invented after the FTM and is provided in the third service pack to NT 4.0, the DCOM patch for Windows 95, and out of the box with Windows 98/2000/XP. If you’re aggregating the FTM and caching interface pointers, you must use the GIT. ATL provides the CComGITPtr class, discussed in Chapter 3, “ATL Smart Types,” to make dealing with the GIT easier.

For an in-depth discussion of the FTM, the GIT, and their use, read Essential COM (Addison-Wesley, 1997), by Don Box.

Interface Map Chaining

C++ programmers are accustomed to using inheritance of implementation for reuse. For example, we reuse the implementation provided in CComObjectRootEx as well as the various ATL implementation classes (such as IDispatchImpl) tHRough inheritance. For each implementation class used, one or more corresponding entries must be made in the interface map. However, what about deriving from a class that already provides an interface map? For example

class CBigBeachBall :
  public CBeachBall,
  public IBigObject {
public:
BEGIN_COM_MAP(CBigBeachBall)
  COM_INTERFACE_ENTRY(IBigObject)
  // All entries from CBeachBall base?
END_COM_MAP()
...
};

COM_INTERFACE_ENTRY_CHAIN

When inheriting from a base class that provides its own interface map, we want to avoid duplicating all the entries in the deriving class’s interface map. The reason is maintenance. If the base class decides to change how it supports an interface or wants to add or remove support for an interface, we’ve got to change the deriving classes, too. It would be much nicer to “inherit” the interface map along with the interface implementations. That’s what COM_INTERFACE_ENTRY_CHAIN does:

#define COM_INTERFACE_ENTRY_CHAIN(classname) \
{ NULL, (DWORD_PTR)&ATL::_CComChainData<classname, \
_ComMapClass>::data, _Chain },

The _CComChainData template simply fills the dw member of the interface entry with a pointer to the base class’s interface map so that the _Chain function can walk that list when evaluating a query request:

static HRESULT WINAPI
CComObjectRootBase::

_Chain(void* pv, REFIID iid,
void** ppvObject, DWORD dw) {
_ATL_CHAINDATA* pcd = (_ATL_CHAINDATA*)dw;
void* p = (void*)((DWORD_PTR)pv + pcd->dwOffset);
return InternalQueryInterface(p, pcd->pFunc(), iid, ppvObject);
}

If the _Chain function returns a failure – for example, if the base class doesn’t support the requested interface – the search continues with the next entry in the table:

class CBigBadBeachBall :
  public CBeachBall,
  public IBigObject,
  public IBadObject {
public:
BEGIN_COM_MAP(CBigBadBeachBall)
  COM_INTERFACE_ENTRY(IBigObject)
COM_INTERFACE_ENTRY_CHAIN(CBeachBall)
COM_INTERFACE_ENTRY(IBadObject)
END_COM_MAP()
...
};

It might seem natural to put the chaining entries first in the interface map. However, remember that the first entry must be a simple entry, so you must put at least one of the derived class’s interfaces first. If the derived class has no additional interfaces, use IUnknown as the first entry:

class CBetterBeachBall :
  public CBeachBall {
public:
BEGIN_COM_MAP(CBetterBeachBall)
COM_INTERFACE_ENTRY(IUnknown)
COM_INTERFACE_ENTRY_CHAIN(CBeachBall)
END_COM_MAP()
...
};

Just Say “No”

COM_INTERFACE_ENTRY_NOINTERFACE

Sometimes, you want to short-circuit the interface request by explicitly returning E_NOINTERFACE when a specific interface is requested. For this, ATL provides COM_INTERFACE_ENTRY_NOINTERFACE:

#define COM_INTERFACE_ENTRY_NOINTERFACE(x) \
{ &_ATL_IIDOF(x), NULL, _NoInterface },

The _NoInterface function does pretty much what you’d expect:

static HRESULT WINAPI
CComObjectRootBase::

_NoInterface(void*, REFIID, void**,
DWORD_PTR)
{ return E_NOINTERFACE; }

This interface map macro is handy when you’ve got blind entries in the interface map, as in blind aggregation or chaining, and you want to remove functionality that the inner object or the base class provides. For example

class CBigNiceBeachBall :
  public CBeachBall,
  public IBigObject {
public:
BEGIN_COM_MAP(CBigNiceBeachBall)
  COM_INTERFACE_ENTRY(IBigObject)
COM_INTERFACE_ENTRY_NOINTERFACE(ILethalObject)
COM_INTERFACE_ENTRY_CHAIN(CBeachBall)
END_COM_MAP()
...
};

Debugging

COM_INTERFACE_ENTRY_BREAK

Sometimes you need to debug your QueryInterface implementation. Maybe you’re building a custom COM_MAP macro. Maybe you’re seeing weird behavior on some interfaces. Sometimes the easiest way to track down a problem is in the debugger. This is where COM_INTERFACE_ENTRY_BREAK comes in:

#define COM_INTERFACE_ENTRY_BREAK(x) \
{ &_ATL_IIDOF(x), NULL, _Break },

The _Break function outputs some helpful debugging information and calls DebugBreak:

static HRESULT WINAPI
CComObjectRootbase::

_Break(void*, REFIID iid, void**, DWORD) {
(iid);
_ATLDUMPIID(iid, _T("Break due to QI for interface "), S_OK);
DebugBreak();
return S_FALSE;
}

The call to DebugBreak is just like a breakpoint set in your debugger. It gives the active debugger the chance to take control of the process. When you’re debugging, you can set other breakpoints and continue executing.

Extensibility

COM_INTERFACE_ENTRY_FUNC and COM_INTERFACE_ENTRY_FUNC_BLIND

ATL provides two macros for putting raw entries into the interface map:

#define COM_INTERFACE_ENTRY_FUNC(iid, dw, func) \
{ &iid, dw, func },

#define COM_INTERFACE_ENTRY_FUNC_BLIND(dw, func) \
{ NULL, dw, func },

These macros are the universal back door to ATL’s implementation of QueryInterface. If you come up with another way of exposing COM interfaces, you can use these macros to achieve them, as long as it lives up to the laws of COM identity.

Direct Access to the this Pointer

One identity trick you can perform using COM_INTERFACE_ENTRY_FUNC was kicked around the ATL Mailing List for quite a while but was ultimately perfected by Don Box. (A slightly modified version of his solution is provided next.) In Chapter 4, “Objects in ATL,” I presented the CreateInstance static member functions of CComObject, CComAgg-Object, and CComPolyObject when using private initialization. The CreateInstance method performed the same job as a Creator would but returned a pointer to the this pointer of the object instead of to only one of the interfaces. This was useful for calling member functions or setting member data that was not exposed via interfaces. We used this technique because it was unsafe to perform a cast. However, why not make QueryInterface perform the cast safely? In other words, why not add an entry to the interface map that returns the object’s this pointer? Imagine a global function with the following implementation:

inline
HRESULT WINAPI _This(void* pv, REFIID iid,
  void** ppvObject, DWORD) {
  ATLASSERT(iid == IID_NULL);
  *ppvObject = pv;
  return S_OK;
}

This function takes the first parameter, pv, which points to the object’s this pointer and hands it out directly in ppvObject. Notice also that this function does not AddRef the resultant interface pointer. Because it’s returning an object pointer, not an interface pointer, it’s not subject to the laws of COM. Remember, the this pointer is useful only within the server. To make sure that any out-of-apartment calls to QueryInterface fail, be sure to pick an interface ID without a proxy-stub, such as IID_NULL.

For example, imagine implementations of the following interfaces, creating a simple object model:

interface IBalloonMan : IUnknown {
    HRESULT CreateBalloon(long rgbColor, IBalloon** ppBalloon);
    HRESULT SwitchColor(IBalloon* pBalloon, long rgbColor);
};

interface IBalloon : IUnknown {
    [propget] HRESULT Color([out, retval] long *pVal);
};

Notice that the balloon’s color can’t be changed via IBalloon, but the implementation of IBalloonMan can give you a balloon of the color you want. If the implementations of IBalloonMan and IBalloon share the same server, the implementation of IBalloon can expose its this pointer via the _This function like this:

class ATL_NO_VTABLE CBalloon :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CBalloon>,
  public IBalloon {
public:
DECLARE_REGISTRY_RESOURCEID(IDR_BALLOON)
DECLARE_NOT_AGGREGATABLE(CBalloon)

DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CBalloon)
  COM_INTERFACE_ENTRY(IBalloon)
COM_INTERFACE_ENTRY_FUNC(IID_NULL, 0, _This)
END_COM_MAP()
    // IBalloon
public:
  STDMETHOD(get_Color)(/*[out, retval]*/ long *pVal);

private:
  COLORREF m_rgbColor;
  friend class CBalloonMan;
};

Because CBalloonMan is a friend of CBalloon, CBalloonMan can set the private color data member of CBalloon, assuming that it can obtain the object’s this pointer. CBalloon’s special entry for IID_NULL lets CBalloonMan do just that:

STDMETHODIMP CBalloonMan::CreateBalloon(long rgbColor,
  IBalloon** ppBalloon) {
  // Create balloon
  *ppBalloon = 0;
  HRESULT     hr = CBalloon::CreateInstance(0, ppBalloon);

  if( SUCCEEDED(hr) ) {
// Use backdoor to acquire CBalloon's this pointer
CBalloon* pBalloonThis = 0;
hr = (*ppBalloon)->QueryInterface(IID_NULL,
(void**)&pBalloonThis);
if( SUCCEEDED(hr) ) {
       // Use CBalloon's this pointer for private initialization
       pBalloonThis->m_rgbColor = rgbColor;
    }
  }
  return hr;
}

The benefit to this technique over the private initialization technique that the CreateInstance member function of CComObject et al exposes is that the this pointer can be obtained after creation:

STDMETHODIMP CBalloonMan::SwitchColor(IBalloon* pBalloon,
  long rgbColor) {
// Use backdoor to acquire CBalloon's this pointer
CBalloon*   pBalloonThis = 0;
HRESULT hr = pBalloon->QueryInterface(IID_NULL, (void**)&pBalloonThis);
if (SUCCEEDED(hr)) {
    hr = pBalloonThis->m_rgbColor = rgbColor;
  }
  return hr;
}

Clearly, this technique is a back-door hack with limited usefulness; it should not be used to subvert the binary boundary between client and object. However, it does have its own special charm. For objects that share the same apartment in the same server, it’s a valid way to discover just who is who. If you find yourself using this technique, you might find the following macro to be a useful shortcut:

#define COM_INTERFACE_ENTRY_THIS() \
        COM_INTERFACE_ENTRY_FUNC(IID_NULL, 0, _This)

Per-Object Interfaces

Sometimes it’s useful to handle interfaces on a per-object basis instead of a per-class basis. Another friend of mine, Martin Gudgin, provided the following example. If you want to implement something known as a “smart proxy,” you have to keep track of the list of interfaces each object supports, and you might not know what those are until runtime. Each smart proxy object has its own list of interfaces, which can easily be managed by a member function. Unfortunately, interface maps can’t hold member functions (believe me, I tried). However, you can use a combination of COM_INTERFACE_ENTRY_FUNC_BLIND and a static member function to perform the forwarding to a member function:

class ATL_NO_VTABLE CSmartProxy :
  public CComObjectRootEx<CComSingleThreadModel>,
  public CComCoClass<CSmartProxy, &CLSID_SmartProxy>,
  public IUnknown
{
public:
DECLARE_REGISTRY_RESOURCEID(IDR_SMARTPROXY)
DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CSmartProxy)
  COM_INTERFACE_ENTRY(IUnknown)
COM_INTERFACE_ENTRY_FUNC_BLIND(0, _QI)
END_COM_MAP()

public:
static HRESULT WINAPI _QI(void* pv, REFIID iid,
void** ppvObject, DWORD) {
// Forward to QI member function
return ((CSmartProxy*)pv)->QI(iid, ppvObject);
}
// Per-object implementation of QI
HRESULT QI(REFIID riid, void** ppv);
};

Of course, you might wonder why you’d go to all this trouble to get back to the per-object implementation of QueryInterface that you’ve come to know and love, but that’s ATL.

Summary

Even when you understand and commit to the laws of COM identity, you’ll find that they aren’t very restrictive. Prefer multiple inheritance, but do not feel that ATL limits you to that technique. You can extend the interface map to support any identity trick that ATL doesn’t support directly.