CComAggObject Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CComAggObject Class on docs.microsoft.com. 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.

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.

Public Constructors

NameDescription
CComAggObject::CComAggObjectThe constructor.
CComAggObject::~CComAggObjectThe destructor.

Public Methods

NameDescription
CComAggObject::AddRefIncrements the reference count on the aggregated object.
CComAggObject::CreateInstanceThis static function allows you to create a new CComAggObject< contained > object without the overhead of CoCreateInstance.
CComAggObject::FinalConstructPerforms final initialization of m_contained.
CComAggObject::FinalReleasePerforms final destruction of m_contained.
CComAggObject::QueryInterfaceRetrieves a pointer to the requested interface.
CComAggObject::ReleaseDecrements the reference count on the aggregated object.

Public Data Members

NameDescription
CComAggObject::m_containedDelegates IUnknown calls to the outer unknown.

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.

CComObjectRootBase

CComObjectRootEx

IUnknown

CComAggObject

Header: atlcom.h

Increments the reference count on the aggregated object.

STDMETHOD_(ULONG, AddRef)();

Return Value

A value that may be useful for diagnostics or testing.

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.

The destructor.

~CComAggObject();

Remarks

Frees all allocated resources, calls FinalRelease, and decrements the module lock count.

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.

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.

Called during object destruction, this method frees the m_contained member.

void FinalRelease();

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.

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.

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.

CComObject Class
CComPolyObject Class
DECLARE_AGGREGATABLE
DECLARE_ONLY_AGGREGATABLE
DECLARE_NOT_AGGREGATABLE
Class Overview

Show: