CComAggObject Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CComAggObject Class.
This class implements the IUnknown interface for an aggregated object. By definition, an aggregated object is contained within an outer object. The CComAggObject class is similar to the CComObject Class, except that it exposes an interface that is directly accessible to external clients.
Syntax
template<class contained>
class CComAggObject : public IUnknown,
public CComObjectRootEx<contained::_ThreadModel::ThreadModelNoCS>
Parameters
contained
Your class, derived from CComObjectRoot or CComObjectRootEx, as well as from any other interfaces you want to support on the object.
Members
Public Constructors
| Name | Description |
|---|---|
| CComAggObject::CComAggObject | The constructor. |
| CComAggObject::~CComAggObject | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CComAggObject::AddRef | Increments the reference count on the aggregated object. |
| CComAggObject::CreateInstance | This static function allows you to create a new CComAggObject< contained > object without the overhead of CoCreateInstance. |
| CComAggObject::FinalConstruct | Performs final initialization of m_contained. |
| CComAggObject::FinalRelease | Performs final destruction of m_contained. |
| CComAggObject::QueryInterface | Retrieves a pointer to the requested interface. |
| CComAggObject::Release | Decrements the reference count on the aggregated object. |
Public Data Members
| Name | Description |
|---|---|
| CComAggObject::m_contained | Delegates IUnknown calls to the outer unknown. |
Remarks
CComAggObject implements IUnknown for an aggregated object. CComAggObject has its own IUnknown interface, separate from the outer object's IUnknown interface, and maintains its own reference count.
For more information about aggregation, see the article Fundamentals of ATL COM Objects.
Inheritance Hierarchy
CComObjectRootBase
IUnknown
CComAggObject
Requirements
Header: atlcom.h
CComAggObject::AddRef
Increments the reference count on the aggregated object.
STDMETHOD_(ULONG, AddRef)();
Return Value
A value that may be useful for diagnostics or testing.
CComAggObject::CComAggObject
The constructor.
CComAggObject(void* pv);
Parameters
pv
[in] The outer unknown.
Remarks
Initializes the CComContainedObject member, m_contained, and increments the module lock count.
The destructor decrements the module lock count.
CComAggObject::~CComAggObject
The destructor.
~CComAggObject();
Remarks
Frees all allocated resources, calls FinalRelease, and decrements the module lock count.
CComAggObject::CreateInstance
This static function allows you to create a new CComAggObject<contained > object without the overhead of CoCreateInstance.
static HRESULT WINAPI CreateInstance(
LPUNKNOWN pUnkOuter,
CComAggObject<contained>** pp);
Parameters
pp
[out] A pointer to a **CComAggObject<**contained > pointer. If CreateInstance is unsuccessful, pp is set to NULL.
Return Value
A standard HRESULT value.
Remarks
The object returned has a reference count of zero, so call AddRef immediately, then use Release to free the reference on the object pointer when you're done.
If you do not need direct access to the object, but still want to create a new object without the overhead of CoCreateInstance, use CComCoClass::CreateInstance instead.
CComAggObject::FinalConstruct
Called during the final stages of object construction, this method performs any final initialization on the m_contained member.
HRESULT FinalConstruct();
Return Value
A standard HRESULT value.
CComAggObject::FinalRelease
Called during object destruction, this method frees the m_contained member.
void FinalRelease();
CComAggObject::m_contained
A CComContainedObject object derived from your class.
CComContainedObject<contained> m_contained;
Parameters
contained
[in] Your class, derived from CComObjectRoot or CComObjectRootEx, as well as from any other interfaces you want to support on the object.
Remarks
All IUnknown calls through m_contained are delegated to the outer unknown.
CComAggObject::QueryInterface
Retrieves a pointer to the requested interface.
STDMETHOD(QueryInterface)(REFIID iid, void** ppvObject);
template <class Q>
HRESULT STDMETHODCALLTYPE QueryInterface(Q** pp);
Parameters
iid
[in] The identifier of the interface being requested.
ppvObject
[out] A pointer to the interface pointer identified by iid. If the object does not support this interface, ppvObject is set to NULL.
pp
[out] A pointer to the interface pointer identified by type Q. If the object does not support this interface, pp is set to NULL.
Return Value
A standard HRESULT value.
Remarks
If the requested interface is IUnknown, QueryInterface returns a pointer to the aggregated object's own IUnknown and increments the reference count. Otherwise, this method queries for the interface through the CComContainedObject member, m_contained.
CComAggObject::Release
Decrements the reference count on the aggregated object.
STDMETHOD_(ULONG, Release)();
Return Value
In debug builds, Release returns a value that may be useful for diagnostics or testing. In non-debug builds, Release always returns 0.
See Also
CComObject Class
CComPolyObject Class
DECLARE_AGGREGATABLE
DECLARE_ONLY_AGGREGATABLE
DECLARE_NOT_AGGREGATABLE
Class Overview