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
| 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
| Function | Description |
|---|---|
| CComTearOffObjectBase | Constructor. |
CComTearOffObjectBase Data Members
| Data member | Description |
|---|---|
| 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
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.