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>

See Also CComCachedTearOffObject


CComTearOffObject Class Members

Methods
AddRefIncrements the reference count for a CComTearOffObject object.
CComTearOffObjectConstructor.
QueryInterfaceReturns a pointer to the requested interface on either your tear-off class or the owner class.
ReleaseDecrements the reference count for a CComTearOffObject object and destroys it.
CComTearOffObjectBase Methods
CComTearOffObjectBaseConstructor.
CComTearOffObjectBase Data Members
m_pOwnerA pointer to a CComObject derived from the owner class.

CComTearOffObject Overview


Methods


CComTearOffObject::AddRef

ULONG AddRef( );

Return Value

A value that may be useful for diagnostics and testing.

Remarks

Increments the reference count of the CComTearOffObject object by 1.

CComTearOffObject Overview | Class Members

See Also CComTearOffObject::Release


CComTearOffObject::CComTearOffObject

CComTearOffObject( void* p );

Parameters

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

Remarks

The constructor. Increments the owner's reference count by 1.

CComTearOffObject Overview | Class Members


CComTearOffObject::CComTearOffObjectBase

CComTearOffObjectBase( );

Remarks

The constructor. Initializes the m_pOwner member to NULL.

CComTearOffObject Overview | Class Members

See Also CComCachedTearOffObject::CComCachedTearOffObject


CComTearOffObject::QueryInterface

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

Return Value

A standard HRESULT value.

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.

Remarks

Retrieves a pointer to the requested interface. 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 Overview | Class Members

See Also CComTearOffObject::AddRef, CComTearOffObject::Release


CComTearOffObject::Release

ULONG Release( );

Return Value

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

Remarks

Decrements the reference count by 1, and if the reference count is 0, deletes the CComTearOffObject.

CComTearOffObject Overview | Class Members

See Also CComTearOffObject::AddRef


Data Members


CComTearOffObject::m_pOwner

CComObject<Owner>* m_pOwner;

Parameters

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

Remarks

A pointer to a CComObject from Owner. The pointer is initialized to NULL during construction.

CComTearOffObject Overview | Class Members

See Also CComTearOffObject::CComTearOffObjectBase