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

CComObjectRootEx

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