Класс COleDispatchDriver

Статья
06/16/2023

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

Синтаксис

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	Указывает указатель на интерфейс, подключенный `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

Поделиться через

Класс COleDispatchDriver

Синтаксис

Участники

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

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

Открытые операторы

Открытые члены данных

Замечания

Иерархия наследования

Требования

COleDispatchDriver::AttachDispatch

Параметры

Замечания

Пример

COleDispatchDriver::COleDispatchDriver

Параметры

Замечания

Пример

COleDispatchDriver::CreateDispatch

Параметры

Возвращаемое значение

Пример

COleDispatchDriver::D etachDispatch

Возвращаемое значение

Замечания

Пример

COleDispatchDriver::GetProperty

Параметры

Пример

COleDispatchDriver::InvokeHelper

Параметры

Замечания

Пример

COleDispatchDriver::m_bAutoRelease

Замечания

Пример

COleDispatchDriver::m_lpDispatch

Замечания

Пример

COleDispatchDriver::operator =

Параметры

COleDispatchDriver::operator LPDISPATCH

Пример

COleDispatchDriver::ReleaseDispatch

Замечания

Пример

COleDispatchDriver::SetProperty

Параметры

Пример

См. также

Обратная связь

Дополнительные ресурсы