CComObject 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 CComObject Class.

This class implements IUnknown for a nonaggregated object.

Syntax

template<class Base>  
class CComObject : public Base

Parameters

Base
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
CComObject::CComObject	The constructor.
CComObject::~CComObject	The destructor.

Public Methods

Name	Description
CComObject::AddRef	Increments the reference count on the object.
CComObject::CreateInstance	(Static) Creates a new CComObject object.
CComObject::QueryInterface	Retrieves a pointer to the requested interface.
CComObject::Release	Decrements the reference count on the object.

Remarks

CComObject implements IUnknown for a nonaggregated object. However, calls to QueryInterface, AddRef, and Release are delegated to CComObjectRootEx.

For more information about using CComObject, see the article Fundamentals of ATL COM Objects.

Inheritance Hierarchy

Base

CComObject

Requirements

Header: atlcom.h

CComObject::AddRef

Increments the reference count on the object.

STDMETHOD_(ULONG, AddRef)();

Return Value

This function returns the new incremented reference count on the object. This value may be useful for diagnostics or testing.

CComObject::CComObject

The constructor increments the module lock count.

CComObject(void* = NULL);

Parameters

void*
[in] This unnamed parameter is not used. It exists for symmetry with other CComXXXObjectXXX constructors.

Remarks

The destructor decrements it.

If a CComObject-derived object is successfully constructed using the new operator, the initial reference count is 0. To set the reference count to the proper value (1), make a call to the AddRef function.

CComObject::~CComObject

The destructor.

CComObject();

Remarks

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

CComObject::CreateInstance

This static function allows you to create a new CComObject<Base> object, without the overhead of CoCreateInstance.

static HRESULT WINAPI CreateInstance(CComObject<Base>** pp);

Parameters

pp
[out] A pointer to a CComObject<Base> 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.

Example

class ATL_NO_VTABLE CMyCircle :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyCircle, &CLSID_MyCircle>,
   public IDispatchImpl<IMyCircle, &IID_IMyCircle, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>
{
public:
   CMyCircle()
   {
   }

DECLARE_REGISTRY_RESOURCEID(IDR_MYCIRCLE)

DECLARE_NOT_AGGREGATABLE(CMyCircle)

BEGIN_COM_MAP(CMyCircle)
   COM_INTERFACE_ENTRY(IMyCircle)
   COM_INTERFACE_ENTRY(IDispatch)
END_COM_MAP()



   DECLARE_PROTECT_FINAL_CONSTRUCT()

   HRESULT FinalConstruct()
   {
      return S_OK;
   }

   void FinalRelease()
   {
   }

public:

public:
   STDMETHOD(get_XCenter)(double* pVal);
};

   // Create a local instance of COM object CMyCircle.
   double x;
   CComObject<CMyCircle>* pCircle;
   HRESULT hRes = CComObject<CMyCircle>::CreateInstance(&pCircle);
   ATLASSERT(SUCCEEDED(hRes));

   // Increment reference count immediately
   pCircle->AddRef();

   // Access method of COM object
   hRes = pCircle->get_XCenter(&x);

   // Decrement reference count when done
   pCircle->Release();
   pCircle = NULL;

CComObject::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.

CComObject::Release

Decrements the reference count on the object.

STDMETHOD_(ULONG, Release)();

Return Value

This function returns the new decremented reference count on the object. In debug builds, the return value may be useful for diagnostics or testing. In non-debug builds, Release always returns 0.

See Also

CComAggObject Class
CComPolyObject Class
DECLARE_AGGREGATABLE
DECLARE_NOT_AGGREGATABLE
Class Overview