Класс COleDispatchDriver

  • Статья

Реализует автоматизацию OLE на стороне клиента.

Синтаксис

class COleDispatchDriver

Участники

Открытые конструкторы

Имя Описание
COleDispatchDriver::COleDispatchDriver Формирует объект COleDispatchDriver.

Открытые методы

Имя Описание
COleDispatchDriver::AttachDispatch Присоединяет подключение к объекту IDispatchCOleDispatchDriver .
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 Указывает указатель на интерфейс, подключенный IDispatch к этому COleDispatchDriver.

Замечания

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( ) без аргументов, необходимо подключиться 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
Указатель на программный идентификатор, например 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 см. в разделе "Реализация интерфейса IDispatch" в пакете SDK для Windows.

Пример

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

Вызывает метод объекта или свойство, указанное dwDispID, в контексте, указанном wFlags.

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

Параметры

dwDispID
Задает вызываемый метод или свойство.

wFlags
Флаги, описывающие контекст вызова IDispatch::Invoke. . Список возможных значений см. в параметре wFlags в IDispatch::Invoke в пакете SDK для Windows.

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 ВАРИАНТ
VT_UNKNOWN LPUNKNOWN

Аргумент pbParamInfo — это разделенный пробелом список констант VTS_ . Одно или несколько из этих значений, разделенных пробелами (не запятыми), составляют список параметров функции. Список возможных значений можно получить с помощью макроса EVENT_CUSTOM .

Эта функция преобразует параметры в значения VARIANTARG, а затем вызывает метод IDispatch::Invoke . Если вызов Invoke завершается сбоем, эта функция создает исключение. Если объект SCODE (код состояния), возвращаемый IDispatch::Invoke DISP_E_EXCEPTION, эта функция создает объект COleException; в противном случае вызывается исключение COleDispatchException.

Дополнительные сведения см. в статье VARIANTARG, реализация интерфейса IDispatch, IDispatch::Invoke и структура кодов ошибок COM в пакете SDK для Windows.

Пример

См. пример для COleDispatchDriver::CreateDispatch.

COleDispatchDriver::m_bAutoRelease

Если значение TRUE, объект COM, к которым обращается m_lpDispatch , автоматически освобождается при вызове ReleaseDispatch или при уничтожении этого COleDispatchDriver объекта.

BOOL m_bAutoRelease;

Замечания

По умолчанию m_bAutoRelease в конструкторе задано значение TRUE.

Дополнительные сведения о выпуске COM-объектов см. в разделе "Реализация подсчета ссылок" и IUnknown::Release в пакете SDK для Windows.

Пример

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

Указатель на интерфейс, подключенный IDispatch к этому COleDispatchDriver.

LPDISPATCH m_lpDispatch;

Замечания

Элемент m_lpDispatch данных — это общедоступная переменная типа LPDISPATCH.

Дополнительные сведения см. в разделе IDispatch в пакете SDK для Windows.

Пример

См. пример 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

Задает свойство объекта OLE, указанное dwDispID.

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);
}

См. также

Пример CALCDRIV MFC
Пример ACDUAL для MFC
Диаграмма иерархии
Класс CCmdTarget