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.

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.

Public Constructors

NameDescription
CComObject::CComObjectThe constructor.
CComObject::~CComObjectThe destructor.

Public Methods

NameDescription
CComObject::AddRefIncrements the reference count on the object.
CComObject::CreateInstance(Static) Creates a new CComObject object.
CComObject::QueryInterfaceRetrieves a pointer to the requested interface.
CComObject::ReleaseDecrements the reference count on the object.

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.

Base

CComObject

Header: atlcom.h

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.

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.

The destructor.

CComObject();

Remarks

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

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;

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.

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.

CComAggObject Class
CComPolyObject Class
DECLARE_AGGREGATABLE
DECLARE_NOT_AGGREGATABLE
Class Overview

Show: