CComTearOffObject

template< class Base >
class CComTearOffObject : public Base

Parameters

Base

Your tear-off class, derived from CComTearOffObjectBase and the interfaces you want your tear-off object to support.

ATL implements its tear-off interfaces in two phases — the CComTearOffObjectBase methods handle the reference count and QueryInterface, while CComTearOffObject implements IUnknown.

CComTearOffObject implements a tear-off interface as a separate object that is instantiated only when that interface is queried for. The tear-off is deleted when its reference count becomes zero. Typically, you build a tear-off interface for an interface that is rarely used, since using a tear-off saves a vtable pointer in all the instances of your main object.

You should derive the class implementing the tear-off from CComTearOffObjectBase and from whichever interfaces you want your tear-off object to support. CComTearOffObjectBase is templatized on the owner class and the thread model. The owner class is the class of the object for which a tear-off is being implemented. If you do not specify a thread model, the default thread model is used.

You should create a COM map for your tear-off class. When ATL instantiates the tear-off, it will create CComTearOffObject<CYourTearOffClass> or CComCachedTearOffObject<CYourTearOffClass>.

For example, in the BEEPER sample, the CBeeper2 class is the tear-off class and the CBeeper class is the owner class:

class CBeeper2 : public ISupportErrorInfo,
                 public CComTearOffObjectBase<CBeeper>
{
public:
   CBeeper2() {}
   STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid)
   {
      return (InlineIsEqualGUID(IID_IBeeper,riid)) ? 
              S_OK : S_FALSE;
   }

   BEGIN_COM_MAP(CBeeper2)
      COM_INTERFACE_ENTRY(ISupportErrorInfo)
   END_COM_MAP()
};

class CBeeper :
   public IDispatchImpl<IBeeper, &IID_IBeeper, 
                        &LIBID_BeeperLib>,
   public CComObjectRoot,
   public CComCoClass<CBeeper, &CLSID_Beeper>
{
public:
   CBeeper();
   BEGIN_COM_MAP(CBeeper)
      COM_INTERFACE_ENTRY(IDispatch)
      COM_INTERFACE_ENTRY(IBeeper)
      COM_INTERFACE_ENTRY_TEAR_OFF(IID_ISupportErrorInfo, 
                             CBeeper2)
   END_COM_MAP()
...
};

#include <atlcom.h>

Class Members

See Also   CComCachedTearOffObject