COleDispatchDriver 類別

發行項
08/04/2024

實作 OLE Automation 的用戶端。

語法

class COleDispatchDriver

成員

公用建構函式

名稱	描述
COleDispatchDriver：：COleDispatchDriver	建構 `COleDispatchDriver` 物件。

公用方法

名稱	描述
COleDispatchDriver：：AttachDispatch	`IDispatch`將連接附加至 `COleDispatchDriver` 物件。
COleDispatchDriver：：CreateDispatch	`IDispatch`建立連接，並將它附加至 `COleDispatchDriver` 物件。
COleDispatchDriver：:D etachDispatch	`IDispatch`中斷連結連線，而不釋放它。
COleDispatchDriver：：GetProperty	取得自動化屬性。
COleDispatchDriver：：InvokeHelper	呼叫自動化方法的協助程式。
COleDispatchDriver：：ReleaseDispatch	釋放連線 `IDispatch` 。
COleDispatchDriver：：SetProperty	設定自動化屬性。

公用運算子

名稱	描述
COleDispatchDriver：：operator =	將來源值 `COleDispatchDriver` 複製到物件中。
COleDispatchDriver：：operator LPDISPATCH	存取基礎 `IDispatch` 指標。

公用資料成員

名稱	描述
COleDispatchDriver：：m_bAutoRelease	指定是否要在期間或物件解構期間`ReleaseDispatch`釋放 `IDispatch` 。
COleDispatchDriver：：m_lpDispatch	表示附加至這個 `COleDispatchDriver`之介面的`IDispatch`指標。

備註

COleDispatchDriver 沒有基類。

OLE 分派介面可讓您存取物件的方法和屬性。附加、卸離、建立和釋放類型的IDispatch分派連接的成員函COleDispatchDriver式。其他成員函式會使用變數自變數清單來簡化呼叫 IDispatch::Invoke。

此類別可以直接使用，但通常只能由 [新增類別精靈] 所建立的類別使用。當您藉由匯入類型庫來建立新的C++類別時，新的類別衍生自 COleDispatchDriver。

如需使用 COleDispatchDriver的詳細資訊，請參閱下列文章：

繼承階層架構

COleDispatchDriver

需求

標頭： afxdisp.h

COleDispatchDriver：：AttachDispatch

呼叫 AttachDispatch 成員函式可將 IDispatch 指標附加至 COleDispatchDriver 物件。如需詳細資訊，請參閱 Implementing the IDispatch Interface。

void AttachDispatch(
    LPDISPATCH lpDispatch,
    BOOL bAutoRelease = TRUE);

參數

lpDispatch
要附加至 IDispatch 物件的 OLE COleDispatchDriver 物件指標。

bAutoRelease
指定當這個物件移出範圍時，是否要釋放此分派。

備註

這個函式會釋放已附加至 IDispatch 物件的任何 COleDispatchDriver 指標。

範例

void COleContainerView::OnAttachDispatch()
{
   CLSID clsidWMP;
   LPDISPATCH pWMPDispatch = NULL;
   COleDispatchDriver oddWMP;

   try
   {
      AfxCheckError(::CLSIDFromProgID(_T("WMPlayer.OCX"), &clsidWMP));

      AfxCheckError(::CoCreateInstance(clsidWMP, NULL, CLSCTX_INPROC_SERVER,
         IID_IDispatch, (LPVOID*)& pWMPDispatch));

      oddWMP.AttachDispatch(pWMPDispatch, TRUE);
      pWMPDispatch = NULL; // our COleDispatchDriver now owns the interface

      CString strUIMode;
      oddWMP.GetProperty(23, VT_BSTR, (void*)& strUIMode);
      TRACE(_T("WMP uiMode is %s.\n"), strUIMode);
   }
   catch (COleException* pe)
   {
      pe->ReportError();
      pe->Delete();
   }
   catch (CMemoryException* pe)
   {
      pe->ReportError();
      pe->Delete();
   }

   // cleanup
   if (NULL != pWMPDispatch)
   {
      pWMPDispatch->Release();
   }

   // COleDispatchDriver automatically releases the dispatch interface when
   // it goes out of scope if m_bAutoRelease is TRUE.
}

COleDispatchDriver：：COleDispatchDriver

建構 COleDispatchDriver 物件。

COleDispatchDriver();
COleDispatchDriver(LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE);
COleDispatchDriver(const COleDispatchDriver& dispatchSrc);

參數

lpDispatch
要附加至 IDispatch 物件的 OLE COleDispatchDriver 物件指標。

bAutoRelease
指定當這個物件移出範圍時，是否要釋放此分派。

dispatchSrc
現有 COleDispatchDriver 對象的參考。

備註

表單 COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) 會連接 IDispatch 介面。

表單 COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) 會複製現有的 COleDispatchDriver 物件，並遞增參考計數。

表單 COleDispatchDriver( ) 會 COleDispatchDriver 建立物件，但不會連接 IDispatch 介面。在使用 COleDispatchDriver( ) 不含自變數之前，您應該 IDispatch 先使用 COleDispatchDriver：：CreateDispatch 或 COleDispatchDriver：：AttachDispatch 連接到它。如需詳細資訊，請參閱 Implementing the IDispatch Interface。

範例

請參閱 COleDispatchDriver::CreateDispatch的範例。

COleDispatchDriver：：CreateDispatch

建立 IDispatch 介面物件並將它附加至 COleDispatchDriver 物件。

BOOL CreateDispatch(
    REFCLSID clsid,
    COleException* pError = NULL);

BOOL CreateDispatch(
    LPCTSTR lpszProgID,
    COleException* pError = NULL);

參數

clsid
要建立的 IDispatch 連接物件類別識別碼。

pError
OLE 例外狀況物件的指標，會保留因建立而產生的狀態碼。

lpszProgID
Automation 物件之程式設計識別項的指標，例如 "Excel.Document.5"，針對此物件會建立分派物件。

傳回值

非零成功，否則為 0。

範例

void COleContainerView::OnCreateDispatch()
{
   COleDispatchDriver disp;
   COleException* pe = new COleException;

   try
   {
      // Create instance of Microsoft System Information Control 
      // by using ProgID.
      if (disp.CreateDispatch(_T("WMPlayer.OCX"), pe))
      {
         //Get uiMode.     
         CString strUIMode;
         disp.InvokeHelper(23, DISPATCH_PROPERTYGET, VT_BSTR,
            (void*)& strUIMode, NULL);

         CString strMsg;
         strMsg.Format(_T("WMP uiMode is %s."), strUIMode);
         AfxMessageBox(strMsg);
      }
      else
      {
         throw pe;
      }
   }
   //Catch control-specific exceptions.
   catch (COleDispatchException* pe)
   {
      CString cStr;

      if (!pe->m_strSource.IsEmpty())
         cStr = pe->m_strSource + _T(" - ");
      if (!pe->m_strDescription.IsEmpty())
         cStr += pe->m_strDescription;
      else
         cStr += _T("unknown error");

      AfxMessageBox(cStr, MB_OK,
         (pe->m_strHelpFile.IsEmpty()) ? 0 : pe->m_dwHelpContext);

      pe->Delete();
   }
   //Catch all MFC exceptions, including COleExceptions.
   // OS exceptions will not be caught.
   catch (CException* pe)
   {
      TRACE(_T("%s(%d): OLE Execption caught: SCODE = %x"),
         __FILE__, __LINE__, COleException::Process(pe));
      pe->Delete();
   }

   pe->Delete();
}

COleDispatchDriver：:D etachDispatch

從這個物件中斷連結目前的 IDispatch 連接。

LPDISPATCH DetachDispatch();

傳回值

先前附加之 OLE IDispatch 物件的指標。

備註

IDispatch未發行。

如需 LPDISPATCH 類型的詳細資訊，請參閱在 Windows SDK 中實作 IDispatch 介面。

範例

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver：：GetProperty

取得 dwDispID 所指定的物件屬性。

void GetProperty(
    DISPID dwDispID,
    VARTYPE vtProp,
    void* pvProp) const;

參數

dwDispID
識別要擷取的屬性。

vtProp
指定要擷取的屬性。如需可能的值，請參閱 COleDispatchDriver::InvokeHelper的＜備註＞一節。

pvProp
將接收屬性值之變數的位址。它必須符合 vtProp 指定的類型。

範例

CString IMyComObject::GetString(DISPID dispid)
{
   CString result;
   GetProperty(dispid, VT_BSTR, (void*)& result);
   return result;
}

COleDispatchDriver::InvokeHelper

在 wFlags 所指定的內容中，呼叫 dwDispID 所指定的物件方法或屬性。

void AFX_CDECL InvokeHelper(
    DISPID dwDispID,
    WORD wFlags,
    VARTYPE vtRet,
    void* pvRet,
    const BYTE* pbParamInfo, ...);

參數

dwDispID
指定所要叫用的屬性或方法。

wFlags
旗標，描述對 IDispatch::Invoke的呼叫內容。 . 如需可能值的清單，請參閱 Windows SDK 中 IDispatch：：Invoke 中的 wFlags 參數。

vtRet
指定傳回值的類型。如需了解可能的值，請參閱＜備註＞一節。

pvRet
要接收屬性值或傳回值之變數的位址。它必須符合 vtRet 所指定的類型。

pbParamInfo
指定 pbParamInfo 下列參數類型的以 Null 終止的位元元元串指標。

...
參數的變數清單，pbParamInfo 中指定的類型。

備註

pbParamInfo 參數會指定傳遞至方法或屬性的參數類型。引數的變數清單會以 ... 語法宣告代表。

vtRet 自變數的可能值取自 VARENUM 列舉。可能值如下所示：

符號	傳回類型
VT_EMPTY	`void`
VT_I2	`short`
VT_I4	`long`
VT_R4	`float`
VT_R8	`double`
VT_CY	CY
VT_DATE	DATE
VT_BSTR	BSTR
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_Variant	變體
VT_UNKNOWN	LPUNKNOWN

pbParamInfo 自變數是VTS_常數的空間分隔清單。其中的一或多個值 (以空格分隔，而非逗號) 會指定函式的參數清單。可能的值會列在 EVENT_CUSTOM 巨集中。

此函式會將參數轉換成 VARIANTARG 值，然後叫用 IDispatch：：Invoke 方法。若呼叫 Invoke 失敗，此函式會擲回例外狀況。如果傳 IDispatch::Invoke 回的 SCODE （狀態代碼）為 DISP_E_EXCEPTION，此函式會擲回 COleException 物件，否則會擲回 COleDispatchException。

如需詳細資訊，請參閱 VARIANTARG、實作 Windows SDK 中的 IDispatch 介面、IDispatch：：Invoke 和 COM 錯誤碼的結構。

範例

請參閱 COleDispatchDriver::CreateDispatch的範例。

COleDispatchDriver：：m_bAutoRelease

如果為 TRUE，m_lpDispatch所存取的 COM 物件會在呼叫 ReleaseDispatch 或終結此COleDispatchDriver物件時自動釋放。

BOOL m_bAutoRelease;

備註

根據預設， m_bAutoRelease 會在建構函式中設定為TRUE。

如需釋放 COM 對象的詳細資訊，請參閱在 Windows SDK 中實作參考計數和 IUnknown：：Release 。

範例

// Clean up by forcing Release to be called
// on COleDispatchDriver object and delete
if (bError)
{
   pDisp->m_bAutoRelease = TRUE;
   delete pDisp;
   pDisp = NULL;
}

COleDispatchDriver：：m_lpDispatch

附加至這個 COleDispatchDriver之介面的IDispatch指標。

LPDISPATCH m_lpDispatch;

備註

數據 m_lpDispatch 成員是 LPDISPATCH 類型的公用變數。

如需詳細資訊，請參閱 Windows SDK 中的 IDispatch 。

範例

請參閱 COleDispatchDriver：：AttachDispatch 的範例。

COleDispatchDriver：：operator =

將來源值 COleDispatchDriver 複製到物件中。

const COleDispatchDriver& operator=(const COleDispatchDriver& dispatchSrc);

參數

dispatchSrc
現有 COleDispatchDriver 物件的指標。

COleDispatchDriver：：operator LPDISPATCH

存取對象的基礎 IDispatch 指標 COleDispatchDriver 。

operator LPDISPATCH();

範例

COleDispatchDriver disp;
if (disp.CreateDispatch(_T("WMPlayer.OCX")))
{
   IDispatch* pDispatch = disp; //COleDispatchDriver::operator
                                //LPDISPATCH is called here
   IUnknown* pUnkn = NULL;
   HRESULT hr = pDispatch->QueryInterface(IID_IUnknown, (void**)& pUnkn);
   if (SUCCEEDED(hr))
   {
      //Do something...
      pUnkn->Release();
   }
}

COleDispatchDriver：：ReleaseDispatch

IDispatch釋放連線。如需詳細資訊，請參閱實作 IDispatch 介面

void ReleaseDispatch();

備註

如果已為此連線設定自動發行，此函式會在釋放介面之前呼叫 IDispatch::Release 。

範例

請參閱 COleDispatchDriver：：AttachDispatch 的範例。

COleDispatchDriver：：SetProperty

設定 dwDispID 所指定的 OLE 物件屬性。

void AFX_CDECL SetProperty(
    DISPID dwDispID,
    VARTYPE vtProp, ...);

參數

dwDispID
識別要設定的屬性。

vtProp
指定要設定的屬性類型。如需可能的值，請參閱 COleDispatchDriver::InvokeHelper的＜備註＞一節。

...
vtProp 所指定類型的單一參數。

範例

void IMyComObject::SetString(DISPID dispid, LPCTSTR propVal)
{
   SetProperty(dispid, VT_BSTR, propVal);
}

另請參閱

MFC 範例 CALCDRIV
MFC 範例 ACDUAL
階層架構圖表
 CCmdTarget 類別

共用方式為