CComPtr 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 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.
Public Constructors
| Name | Description |
|---|---|
| CComPtr::CComPtr | The constructor. |
Public Operators
| Name | Description |
|---|---|
| CComPtr::operator = | Assigns a pointer to the member pointer. |
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:
// 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.
CComPtr
Header: atlbase.h
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.
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.