CComPtr Class

A smart pointer class for managing COM interface pointers.

Syntax

template<class T>
class CComPtr

Parameters

T
A COM interface specifying the type of pointer to be stored.

Members

Public Constructors

Public Operators

Remarks

ATL uses CComPtr and CComQIPtr to manage COM interface pointers. Both are derived from CComPtrBase, and both do automatic reference counting.

The CComPtr and CComQIPtr classes can help eliminate memory leaks by performing automatic reference counting. The following functions both do the same logical operations. However, the second version may be less error-prone because it uses the CComPtr class:

// Error-checking routine that performs manual lifetime management
// of a COM IErrorInfo object
HRESULT CheckComError_Manual()
{
   HRESULT hr;
   CComBSTR bstrDescription; 
   CComBSTR bstrSource; 
   CComBSTR bstrHelpFile; 

   IErrorInfo* pErrInfo = NULL; // naked COM interface pointer
   hr = ::GetErrorInfo(0, &pErrInfo);
   if(hr != S_OK)
      return hr;

   hr = pErrInfo->GetDescription(&bstrDescription); 
   if(FAILED(hr))
   {
      pErrInfo->Release();   // must release interface pointer before returning
      return hr;
   }

   hr = pErrInfo->GetSource(&bstrSource);
   if(FAILED(hr))
   {
      pErrInfo->Release();   // must release interface pointer before returning
      return hr;
   }

   hr = pErrInfo->GetHelpFile(&bstrHelpFile);
   if(FAILED(hr))
   {
      pErrInfo->Release();   // must release interface pointer before returning
      return hr;
   }

   pErrInfo->Release();      // must release interface pointer before returning
   return S_OK;
}

// Error-checking routine that performs automatic lifetime management
// of a COM IErrorInfo object through a CComPtr smart pointer object
HRESULT CheckComError_SmartPtr()
{
   HRESULT hr;
   CComBSTR bstrDescription; 
   CComBSTR bstrSource; 
   CComBSTR bstrHelpFile; 

   CComPtr<IErrorInfo> pErrInfo; 
   hr = ::GetErrorInfo(0, &pErrInfo);
   if(hr != S_OK)
      return hr;

   hr = pErrInfo->GetDescription(&bstrDescription); 
   if(FAILED(hr))
      return hr;

   hr = pErrInfo->GetSource(&bstrSource);
   if(FAILED(hr))
      return hr;

   hr = pErrInfo->GetHelpFile(&bstrHelpFile);
   if(FAILED(hr))
      return hr;

   return S_OK;
}   // CComPtr will auto-release underlying IErrorInfo interface pointer as needed

In Debug builds, link atlsd.lib for code tracing.

Inheritance Hierarchy

CComPtrBase

CComPtr

Requirements

Header: atlbase.h

CComPtr::CComPtr

The constructor.

CComPtr() throw ();
CComPtr(T* lp) throw ();
CComPtr (const CComPtr<T>& lp) throw ();

Parameters

lp
Used to initialize the interface pointer.

T
A COM interface.

Remarks

The constructors that take an argument call AddRef on lp, if it isn't a null pointer. A non-null owned object gets a Release call upon the CComPtr object's destruction, or if a new object is assigned to the CComPtr object.

CComPtr::operator =

Assignment operator.

T* operator= (T* lp) throw ();
T* operator= (const CComPtr<T>& lp) throw ();

Return Value

Returns a pointer to the updated CComPtr object

Remarks

This operation AddRefs the new object and releases the existing object, if one exists.

See also

CComPtr::CComPtr
CComQIPtr::CComQIPtr
Class Overview