共用方式為

How to： 建立和使用 CComPtr 和 CComQIPtr 執行個體

  • 發行項

在傳統 Windows 程式設計中，為 COM 物件 (或函數，為 COM 伺服器)，通常會實作程式庫。許多 Windows 作業系統元件會實作為 COM 伺服器，並且許多參與者提供這種形式的文件庫。COM 的基本概念的相關資訊，請參閱Component Object Model (COM)。

當您具現化元件物件模型 (COM) 物件時，可將介面指標儲存在 COM 智慧型指標，會執行參考計數藉由呼叫AddRef和Release解構函式中。如果您正在使用使用中的樣板程式庫 (ATL) 或程式庫 (MFC)，則請使用CComPtr的智慧型指標。如果您不使用 ATL 或 MFC，則請使用**_com_ptr_t**。因為沒有任何 COM 相當於std::unique_ptr，單一擁有者和多個擁有者的情況下使用這些智慧型指標。兩者都CComPtr和ComQIPtr支援移動有右值參考的作業。

範例

下列範例示範如何使用CComPtr ，COM 物件具現化，並取得其介面指標。請注意， CComPtr::CoCreateInstance成員函式用來建立 COM 物件，而非 Win32 函式具有相同的名稱。

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及其親戚屬於 ATL 和 atlcomcli.h 中所定義。_com_ptr_t在 comip.h 中宣告。編譯器會建立特製化的**_com_ptr_t**就會產生型別程式庫的包裝函式類別。

ATL 也提供CComQIPtr，其中有更簡單的查詢抓取其他介面的 COM 物件的語法。然而，我們建議您CComPtr但並非所有項目，因為CComQIPtr辦得到，並使用一般 COM 介面指標語意上更具一致性。如果您使用CComPtr來查詢介面時，新的介面指標置於 out 參數。如果呼叫失敗，便會傳回 HRESULT，也就是典型的 COM 模式。與CComQIPtr、 傳回值是指標本身，以及如果呼叫失敗，無法存取內部的 HRESULT 傳回值。以下兩個線條的顯示方式的錯誤處理機制，在CComPtr和CComQIPtr不同。

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

CComPtr提供特製化 IDispatch，讓它可以儲存指標 COM 自動化元件，並使用晚期繫結來叫用的介面上的方法。CComDispatchDriver是的 typedef CComQIPtr<IDispatch, &IIDIDispatch>，也就是隱含轉換成CComPtr<IDispatch>。因此，當任何這些三個名稱出現在程式碼，它相當於CComPtr<IDispatch>。下列範例顯示如何取得變數的指標，Microsoft Word 物件模型使用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();
}

請參閱

概念

智慧型指標 (現代的 C++)