CComTearOffObject Class

This class implements a tear-off interface.

Syntax

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

Public Methods

CComTearOffObjectBase Methods

CComTearOffObjectBase Data Members

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

CComTearOffObject::AddRef

Increments the reference count of the CComTearOffObject object by one.

STDMETHOD_(ULONG, AddRef)();

Return Value

A value that may be useful for diagnostics and testing.

CComTearOffObject::CComTearOffObject

The constructor.

CComTearOffObject(void* pv);

Parameters

pv
[in] Pointer that will be converted to a pointer to a CComObject<Owner> object.

Remarks

Increments the owner's reference count by one.

CComTearOffObject::~CComTearOffObject

The destructor.

~CComTearOffObject();

Remarks

Frees all allocated resources, calls FinalRelease, and decrements the module lock count.

CComTearOffObject::CComTearOffObjectBase

The constructor.

CComTearOffObjectBase();

Remarks

Initializes the m_pOwner member to NULL.

CComTearOffObject::m_pOwner

A pointer to a CComObject object derived from Owner.

CComObject<Owner>* m_pOwner;

Parameters

Owner
[in] The class for which a tear-off is being implemented.

Remarks

The pointer is initialized to NULL during construction.

CComTearOffObject::QueryInterface

Retrieves a pointer to the requested interface.

STDMETHOD(QueryInterface)(REFIID iid, void** ppvObject);

Parameters

iid
[in] The IID of the interface being requested.

ppvObject
[out] A pointer to the interface pointer identified by iid, or NULL if the interface is not found.

Return Value

A standard HRESULT value.

Remarks

Queries first for interfaces on your tear-off class. If the interface is not there, queries for the interface on the owner object. If the requested interface is IUnknown, returns the IUnknown of the owner.

CComTearOffObject::Release

Decrements the reference count by one and, if the reference count is zero, deletes the CComTearOffObject.

STDMETHOD_ULONG Release();

Return Value

In non-debug builds, always returns zero. In debug builds, returns a value that may be useful for diagnostics or testing.

See also

CComCachedTearOffObject Class
Class Overview