COleDispatchDriver 类

  • 项目

实现 OLE 自动化的客户端。

语法

class COleDispatchDriver

成员

公共构造函数

名称 描述
COleDispatchDriver::COleDispatchDriver 构造 COleDispatchDriver 对象。

公共方法

名称 描述
COleDispatchDriver::AttachDispatch 将 IDispatch 连接附加到 COleDispatchDriver 对象。
COleDispatchDriver::CreateDispatch 创建 IDispatch 连接并将其附加到 COleDispatchDriver 对象。
COleDispatchDriver::DetachDispatch 分离 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 调度接口提供对对象的方法和属性的访问权限。 COleDispatchDriver 的成员函数会附加、分离、创建和释放类型 IDispatch 的调度连接。 其他成员函数使用变量参数列表来简化调用 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
指向 OLE IDispatch 对象的指针被附加到 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
指向 OLE IDispatch 对象的指针被附加到 COleDispatchDriver 对象。

bAutoRelease
指定当此对象超出范围时是否要释放调度。

dispatchSrc
对现有 COleDispatchDriver 对象的引用。

备注

窗体 COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) 连接 IDispatch 接口。

窗体 COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) 复制现有 COleDispatchDriver 对象并递增引用计数。

窗体 COleDispatchDriver( ) 创建一个 COleDispatchDriver 对象，但不连接 IDispatch 接口。 在使用无参数的 COleDispatchDriver( ) 之前，应使用 COleDispatchDriver::CreateDispatch 或 COleDispatchDriver::AttachDispatch 将 IDispatch 连接到它。 有关更多信息，请参见 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 连接对象的类 ID。

pError
指向 OLE 异常对象的指针，它将保存因创建而产生的状态代码。

lpszProgID
指向要为其创建调度对象的自动化对象的编程标识符的指针，如“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::DetachDispatch

从此对象分离当前 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
指向以 null 结尾的字节字符串的指针，可指定 pbParamInfo 后面的参数的类型。

[.]
具有 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 VARIANT
VT_UNKNOWN LPUNKNOWN

pbParamInfo 参数是 VTS_ 常量的以空格分隔的列表。 其中一个或多个值（由空格（而不是逗号）分隔）指定函数的参数列表。 可能值使用 EVENT_CUSTOM 宏来列出。

此函数将参数转换为 VARIANTARG 值，然后调用 IDispatch::Invoke 方法。 如果 Invoke 调用失败，则此函数会引发异常。 如果 IDispatch::Invoke 返回的 SCODE（状态代码）是 DISP_E_EXCEPTION，此函数会引发 COleException 对象；否则引发 COleDispatchException。

有关详细信息，请参阅 VARIANTARG、实现 IDispatch 接口、IDispatch::Invoke 以及 Windows SDK 中的 COM 错误代码结构。

示例

请参阅 COleDispatchDriver::CreateDispatch的示例。

COleDispatchDriver::m_bAutoRelease

如果为 TRUE，则调用 ReleaseDispatch 或销毁此 COleDispatchDriver 对象时，m_lpDispatch 访问的 COM 对象将自动释放。

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

访问 COleDispatchDriver 对象的基础 IDispatch 指针。

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 类