description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CComTearOffObject Class |
CComTearOffObject Class |
11/04/2016 |
|
|
d974b598-c6b2-42b1-8360-9190d9d0fbf3 |
This class implements a tear-off interface.
template<class Base>
class CComTearOffObject : public Base
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.
Name | Description |
---|---|
CComTearOffObject::CComTearOffObject | The constructor. |
CComTearOffObject::~CComTearOffObject | The destructor. |
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. |
Function | Description |
---|---|
CComTearOffObjectBase | Constructor. |
Data member | Description |
---|---|
m_pOwner | A pointer to a CComObject derived from the owner class. |
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:
[!code-cppNVC_ATL_COM#43]
Base
CComTearOffObject
Header: atlcom.h
Increments the reference count of the CComTearOffObject
object by one.
STDMETHOD_(ULONG, AddRef)();
A value that may be useful for diagnostics and testing.
The constructor.
CComTearOffObject(void* pv);
pv
[in] Pointer that will be converted to a pointer to a CComObject<Owner>
object.
Increments the owner's reference count by one.
The destructor.
~CComTearOffObject();
Frees all allocated resources, calls FinalRelease, and decrements the module lock count.
The constructor.
CComTearOffObjectBase();
Initializes the m_pOwner member to NULL.
A pointer to a CComObject object derived from Owner.
CComObject<Owner>* m_pOwner;
Owner
[in] The class for which a tear-off is being implemented.
The pointer is initialized to NULL during construction.
Retrieves a pointer to the requested interface.
STDMETHOD(QueryInterface)(REFIID iid, void** ppvObject);
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.
A standard HRESULT value.
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.
Decrements the reference count by one and, if the reference count is zero, deletes the CComTearOffObject
.
STDMETHOD_ULONG Release();
In non-debug builds, always returns zero. In debug builds, returns a value that may be useful for diagnostics or testing.