How to: Create and Use CComPtr and CComQIPtr Instances

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 How to: Create and Use CComPtr and CComQIPtr Instances. In classic Windows programming, libraries are often implemented as COM objects (or more precisely, as COM servers). Many Windows operating system components are implemented as COM servers, and many contributors provide libraries in this form. For information about the basics of COM, see Component Object Model (COM).

When you instantiate a Component Object Model (COM) object, store the interface pointer in a COM smart pointer, which performs the reference counting by using calls to AddRef and Release in the destructor. If you are using the Active Template Library (ATL) or the Microsoft Foundation Class Library (MFC), then use the CComPtr smart pointer. If you are not using ATL or MFC, then use _com_ptr_t. Because there is no COM equivalent to std::unique_ptr, use these smart pointers for both single-owner and multiple-owner scenarios. Both CComPtr and ComQIPtr support move operations that have rvalue references.

Example

The following example shows how to use CComPtr to instantiate a COM object and obtain pointers to its interfaces. Notice that the CComPtr::CoCreateInstance member function is used to create the COM object, instead of the Win32 function that has the same name.

void CComPtrDemo()
{

    HRESULT hr = CoInitialize(NULL);

    // Declare the smart pointer.
    CComPtr<IGraphBuilder> pGraph;

    // Use its member function CoCreateInstance to
    // create the COM object and obtain the IGraphBuilder pointer.
    hr = pGraph.CoCreateInstance(CLSID_FilterGraph);
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Use the overloaded -> operator to call the interface methods.
    hr = pGraph->RenderFile(L"C:\\Users\\Public\\Music\\Sample Music\\Sleep Away.mp3", NULL);
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Declare a second smart pointer and use it to 
    // obtain another interface from the object.
    CComPtr<IMediaControl> pControl;
    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pControl));
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Obtain a third interface.
    CComPtr<IMediaEvent> pEvent;
    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pEvent));
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Use the second interface.
    hr = pControl->Run();
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Use the third interface.
    long evCode = 0;
    pEvent->WaitForCompletion(INFINITE, &evCode);

    CoUninitialize();

    // Let the smart pointers do all reference counting.
}

CComPtr and its relatives are part of the ATL and are defined in atlcomcli.h. _com_ptr_t is declared in comip.h. The compiler creates specializations of _com_ptr_t when it generates wrapper classes for type libraries.

Example

ATL also provides CComQIPtr, which has a simpler syntax for querying a COM object to retrieve an additional interface. However, we recommend CComPtr because it does everything that CComQIPtr can do and is semantically more consistent with raw COM interface pointers. If you use a CComPtr to query for an interface, the new interface pointer is placed in an out parameter. If the call fails, an HRESULT is returned, which is the typical COM pattern. With CComQIPtr, the return value is the pointer itself, and if the call fails, the internal HRESULT return value cannot be accessed. The following two lines show how the error handling mechanisms in CComPtr and CComQIPtr differ.

    // CComPtr with error handling:
    CComPtr<IMediaControl> pControl;
    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pControl));
    if(FAILED(hr)){ /*... handle hr error*/ }

    // CComQIPtr with error handling
    CComQIPtr<IMediaEvent> pEvent = pControl;
    if(!pEvent){ /*... handle NULL pointer error*/ }

    // Use the second interface.
    hr = pControl->Run();
    if(FAILED(hr)){ /*... handle hr error*/ }

Example

CComPtr provides a specialization for IDispatch that enables it to store pointers to COM automation components and invoke the methods on the interface by using late binding. CComDispatchDriver is a typedef for CComQIPtr<IDispatch, &IIDIDispatch>, which is implicitly convertible to CComPtr<IDispatch>. Therefore, when any of these three names appears in code, it is equivalent to CComPtr<IDispatch>. The following example shows how to obtain a pointer to the Microsoft Word object model by using a CComPtr<IDispatch>.

void COMAutomationSmartPointerDemo()
{

    CComPtr<IDispatch> pWord;
    CComQIPtr<IDispatch, &IID_IDispatch> pqi = pWord;
    CComDispatchDriver pDriver = pqi;

    HRESULT hr;
    _variant_t pOutVal;

    CoInitialize(NULL);
    hr = pWord.CoCreateInstance(L"Word.Application", NULL, CLSCTX_LOCAL_SERVER);    
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Make Word visible.
    hr = pWord.PutPropertyByName(_bstr_t("Visible"),  &_variant_t(1));
    if(FAILED(hr)){ /*... handle hr error*/ }

    // Get the Documents collection and store it in new CComPtr
    hr = pWord.GetPropertyByName(_bstr_t("Documents"), &pOutVal);
    if(FAILED(hr)){ /*... handle hr error*/ }

    CComPtr<IDispatch> pDocuments = pOutVal.pdispVal; 

    // Use Documents to open a document
    hr = pDocuments.Invoke1 (_bstr_t("Open"), &_variant_t("c:\\users\\public\\documents\\sometext.txt"),&pOutVal);
    if(FAILED(hr)){ /*... handle hr error*/ }

    CoUninitialize();
}

See Also

Smart Pointers