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
Methods | |
AddRef | Increments the reference count for a CComTearOffObject object. |
CComTearOffObject | Constructor. |
QueryInterface | Returns a pointer to the requested interface on either your tear-off class or the owner class. |
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. |
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( 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
CComTearOffObjectBase( );
Remarks
The constructor. Initializes the m_pOwner member to NULL.
CComTearOffObject Overview | Class Members
See Also CComCachedTearOffObject::CComCachedTearOffObject
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
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
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.