COleDispatchDriver 类

项目
10/16/2023

实现 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。

示例