CComPtr Class

MSDN Library
Development Tools and Languages
Visual Studio 2008
Visual Studio
Visual C++
Visual C++ Reference
Visual C++ Libraries Reference
ATL
ATL Classes

CComPtr Class

CComPtr Members
CComPtr Methods
CComPtr Operators

Related Links

CComPtr Class
This page is specific to:.NET Framework Version:1.1 2.03.54.0

ATL Library Reference

CComPtr Class

A smart pointer class for managing COM interface pointers.

template<
   class T 
>
class CComPtr

Parameters

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

Remarks

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

The CComPtr and CComQIPtr classes can help eliminate memory leaks by performing automatic reference counting. The following functions both perform the same logical operations; however, note how the second version may be less error-prone by using the CComPtr class:

C++

Copy to Clipboard Print

// 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;
}

C++

Copy to Clipboard Print

// 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.

Requirements

Header: atlbase.h

Reference

CComPtr::CComPtr

CComQIPtr::CComQIPtr

Other Resources

CComPtr Members

ATL Class Overview

Community Content

CComPtr gotcha's

Added by:Giovanni Dicanio

Couple of very interesting readings to avoid CComPtr misuse:

"The difference between assignment and attachment with ATL smart pointers"
http://blogs.msdn.com/oldnewthing/archive/2009/11/20/9925918.aspx

"Type safety issue when assigning CComPtr<T> instances"
http://blogs.msdn.com/jaredpar/archive/2009/11/04/type-safety-issue-when-assigning-ccomptr-t-instances.aspx