CComTearOffObject Class

Article
01/08/2013

This class implements a tear-off interface.

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.

Members

Public Constructors

Name	Description
CComTearOffObject::CComTearOffObject	The constructor.
CComTearOffObject::~CComTearOffObject	The destructor.

Public Methods

Name	Description
CComTearOffObject::AddRef	Increments the reference count for a CComTearOffObject object.
CComTearOffObject::QueryInterface	Returns a pointer to the requested interface on either your tear-off class or the owner class.
CComTearOffObject::Release	Decrements the reference count for a CComTearOffObject object and destroys it.

CComTearOffObjectBase Methods

CComTearOffObjectBase

Constructor.

CComTearOffObjectBase Data Members

m_pOwner

A pointer to a CComObject derived from the owner class.

Remarks

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 ATL_NO_VTABLE CBeeper :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CBeeper, &CLSID_Beeper>,
   public IDispatchImpl<IBeeper, &IID_IBeeper, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
public:
   CBeeper()
   {
   }

DECLARE_REGISTRY_RESOURCEID(IDR_BEEPER)

DECLARE_NOT_AGGREGATABLE(CBeeper)

BEGIN_COM_MAP(CBeeper)
   COM_INTERFACE_ENTRY(IBeeper)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY_TEAR_OFF(IID_ISupportErrorInfo, CBeeper2)
END_COM_MAP()

// ISupportsErrorInfo
   STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid);


   DECLARE_PROTECT_FINAL_CONSTRUCT()

   HRESULT FinalConstruct()
   {
      return S_OK;
   }

   void FinalRelease()
   {
   }

public:

};

Inheritance Hierarchy

Base

CComTearOffObject

Requirements

Header: atlcom.h

Share via