Classe COleDispatchDriver

Implementa o lado do cliente da automação OLE.

Sintaxe

class COleDispatchDriver

Membros

Construtores públicos

Nome	Descrição
COleDispatchDriver::COleDispatchDriver	Constrói um objeto COleDispatchDriver.

Métodos públicos

Nome	Descrição
COleDispatchDriver::AttachDispatch	Anexa uma conexão IDispatch ao objeto COleDispatchDriver.
COleDispatchDriver::CreateDispatch	Cria uma conexão IDispatch e a anexa ao objeto COleDispatchDriver.
COleDispatchDriver::DetachDispatch	Desanexa uma conexão IDispatch, sem liberá-la.
COleDispatchDriver::GetProperty	Obtém uma propriedade de automação.
COleDispatchDriver::InvokeHelper	Auxiliar para chamar métodos de automação.
COleDispatchDriver::ReleaseDispatch	Libera uma conexão IDispatch.
COleDispatchDriver::SetProperty	Define uma propriedade de automação.

Operadores públicos

Nome	Descrição
COleDispatchDriver::operator =	Copia o valor de origem no objeto COleDispatchDriver.
COleDispatchDriver::operator LPDISPATCH	Acessa o ponteiro IDispatch subjacente.

Membros de Dados Públicos

Nome	Descrição
COleDispatchDriver::m_bAutoRelease	Especifica se é devido liberar o IDispatch durante ReleaseDispatch ou a destruição de objeto.
COleDispatchDriver::m_lpDispatch	Indica o ponteiro para a interface IDispatch anexada a esse COleDispatchDriver.

Comentários

COleDispatchDriver não tem uma classe base.

As interfaces de expedição OLE fornecem acesso aos métodos e propriedades de um objeto. Funções membro de COleDispatchDriver anexam, desanexam, criam e liberam uma conexão de expedição do tipo IDispatch. Outras funções de membro usam listas de argumentos variáveis para simplificar a chamada IDispatch::Invoke.

Essa classe pode ser usada diretamente, mas geralmente é usada somente por classes criadas pelo assistente Adicionar Classe. Quando você cria novas classes C++ importando uma biblioteca de tipos, as novas classes são derivadas de COleDispatchDriver.

Para obter mais informações sobre o uso de COleDispatchDriver, consulte os seguintes artigos:

• Clientes de automação

• Servidores de automação

Hierarquia de herança

COleDispatchDriver

Requisitos

Cabeçalho afxdisp.h

COleDispatchDriver::AttachDispatch

Chame a função membro AttachDispatch para anexar um ponteiro IDispatch ao objeto COleDispatchDriver. Para obter mais informações, confira Como implementar a interface IDispatch.

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

Parâmetros

lpDispatch
Ponteiro para um objeto IDispatch OLE que será anexado ao objeto COleDispatchDriver.

bAutoRelease
Especifica se a expedição deve ser liberada quando esse objeto sair do escopo.

Comentários

Essa função libera um ponteiro IDispatch que já está anexado ao objeto COleDispatchDriver.

Exemplo

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

Constrói um objeto COleDispatchDriver.

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

Parâmetros

lpDispatch
Ponteiro para um objeto IDispatch OLE que será anexado ao objeto COleDispatchDriver.

bAutoRelease
Especifica se a expedição deve ser liberada quando esse objeto sair do escopo.

dispatchSrc
Referência a um objeto COleDispatchDriver existente.

Comentários

O formulário COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) conecta a interface IDispatch.

O formulário COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) copia um objeto COleDispatchDriver existente e incrementa a contagem de referência.

O formulário COleDispatchDriver( ) cria um objeto COleDispatchDriver, mas não conecta a interface IDispatch. Antes de usar COleDispatchDriver( ) sem argumentos, você deve conectar um IDispatch a ele usando COleDispatchDriver::CreateDispatch ou COleDispatchDriver::AttachDispatch. Para obter mais informações, confira Como implementar a interface IDispatch.

Exemplo

Confira o exemplo de COleDispatchDriver::CreateDispatch.

COleDispatchDriver::CreateDispatch

Cria um objeto de interface IDispatch e o anexa ao objeto COleDispatchDriver.

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

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

Parâmetros

clsid
ID de classe do objeto IDispatch de conexão que será criado.

pError
Ponteiro para um objeto de exceção OLE, que reterá o código de status resultante da criação.

lpszProgID
Ponteiro para o identificador programático, como "Excel.Document.5", do objeto de automação para o qual o objeto de expedição deve ser criado.

Valor de retorno

Diferente de zero em caso de êxito. Caso contrário, 0.

Exemplo

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

Desanexa a conexão IDispatch atual desse objeto.

LPDISPATCH DetachDispatch();

Valor de retorno

Um ponteiro para o objeto IDispatch OLE anexado anteriormente.

Comentários

O IDispatch não foi liberado.

Para obter mais informações sobre o tipo LPDISPATCH, consulte Implementar a interface IDispatch no SDK do Windows.

Exemplo

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver::GetProperty

Obtém a propriedade do objeto especificada por dwDispID.

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

Parâmetros

dwDispID
Identifica a propriedade a ser recuperada.

vtProp
Especifica a propriedade que será recuperada. Para obter valores possíveis, consulte a seção Comentários para COleDispatchDriver::InvokeHelper.

pvProp
Endereço da variável que receberá o valor da propriedade. Ele deve corresponder ao tipo especificado por vtProp.

Exemplo

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

COleDispatchDriver::InvokeHelper

Chama o método ou a propriedade do objeto especificado por dwDispID, no contexto especificado por wFlags.

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

Parâmetros

dwDispID
Identifica o método ou a propriedade que será invocada.

wFlags
Sinalizadores que descrevem o contexto da chamada de IDispatch::Invoke. . Para obter uma lista de valores possíveis, consulte o parâmetro wFlags em IDispatch::Invoke no SDK do Windows.

vtRet
Especifica o tipo de valor retornado. Para valores possíveis, consulte a seção Comentários.

pvRet
Endereço da variável que receberá o valor da propriedade ou o valor retornado. Ele deve corresponder ao tipo especificado por vtRet.

pbParamInfo
Ponteiro para uma cadeia de cadeia de caracteres de bytes com terminada em valor nulo que especifica os tipos dos parâmetros que seguem pbParamInfo.

...
Lista variável de parâmetros, de tipos especificados em pbParamInfo.

Comentários

O parâmetro pbParamInfo especifica os tipos dos parâmetros passados para o método ou propriedade. A lista variável de argumentos é representada por ... na declaração de sintaxe.

Os valores possíveis para o argumento vtRet são obtidos da enumeração VARENUM. Os valores possíveis são:

Símbolo	Tipo de retorno
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

O argumento pbParamInfo é uma lista separada por espaços de constantes VTS_. Um ou mais desses valores, separados por espaços (não vírgulas), especifica a lista de parâmetros da função. Os valores possíveis são listados com a macro EVENT_CUSTOM.

Essa função converte os parâmetros em valores VARIANTARG e invoca o método IDispatch::Invoke. Se a chamada de Invoke falhar, essa função gerará uma exceção. Se o SCODE (código de status) retornado for IDispatch::Invoke DISP_E_EXCEPTION, essa função gerará um objeto COleException, caso contrário, ele gerará um COleDispatchException.

Para obter mais informações, consulte VARIANTARG, Implementar a interface do IDispatch, IDispatch::Invoke e a Estrutura de códigos de erro COM no SDK do Windows.

Exemplo

Confira o exemplo de COleDispatchDriver::CreateDispatch.

COleDispatchDriver::m_bAutoRelease

Se TRUE, o objeto COM acessado por m_lpDispatch será liberado automaticamente quando ReleaseDispatch for chamado ou quando esse objeto COleDispatchDriver for destruído.

BOOL m_bAutoRelease;

Comentários

Por padrão, m_bAutoRelease é definido como TRUE no construtor.

Para obter mais informações sobre como liberar objetos COM, consulte Implementar a contagem de referências e IUnknown::Release no SDK do Windows.

Exemplo

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

O ponteiro para a interface IDispatch anexada a esse COleDispatchDriver.

LPDISPATCH m_lpDispatch;

Comentários

O membro de dados m_lpDispatch é uma variável pública do tipo LPDISPATCH.

Para saber mais, confira IDispatch no SDK do Windows.

Exemplo

Confira o exemplo de COleDispatchDriver::AttachDispatch.

COleDispatchDriver::operator =

Copia o valor de origem no objeto COleDispatchDriver.

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

Parâmetros

dispatchSrc
Um ponteiro para um objeto COleDispatchDriver existente.

COleDispatchDriver::operator LPDISPATCH

Acessa o ponteiro IDispatch subjacente ao objeto COleDispatchDriver.

operator LPDISPATCH();

Exemplo

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

Libera a conexão IDispatch. Para obter mais informações, confira Implementar a interface do IDispatch

void ReleaseDispatch();

Comentários

Se a versão automática tiver sido definida para essa conexão, essa função chamará IDispatch::Release antes de liberar a interface.

Exemplo

Confira o exemplo de COleDispatchDriver::AttachDispatch.

COleDispatchDriver::SetProperty

Define a propriedade do objeto OLE especificada por dwDispID.

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

Parâmetros

dwDispID
Identifica a propriedade a ser definida.

vtProp
Especifica o tipo da propriedade que será definida. Para obter valores possíveis, consulte a seção Comentários para COleDispatchDriver::InvokeHelper.

...
Um único parâmetro do tipo especificado por vtProp.

Exemplo

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

Confira também

CALCDRIV de exemplo do MFC
ACDUAL de exemplo do MFC
Gráfico da hierarquia
Classe CCmdTarget