Classe COleDispatchDriver

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

Sintaxe

class COleDispatchDriver

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Membros de Dados Públicos

Observações

COleDispatchDriver não tem uma classe base.

As interfaces de despacho OLE fornecem acesso aos métodos e propriedades de um objeto. Funções membros de COleDispatchDriver anexar, destacar, criar e libertar uma ligação de despacho do tipo IDispatch. Outras funções membros usam listas de argumentos variáveis para simplificar a chamada IDispatch::Invokede .

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

Para mais informações sobre a utilização COleDispatchDriverde , consulte os seguintes artigos:

• Clientes de automação

• Servidores de automação

Hierarquia de herança

COleDispatchDriver

Requerimentos

Cabeçalho: afxdisp.h

COLEDispatchDriver::AnexarDispatch

Chame a AttachDispatch função membro para anexar um IDispatch ponteiro ao COleDispatchDriver objeto. Para mais informações, consulte Implementar a Interface IDispatch.

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

Parâmetros

lpDispatch
Apontador para um objeto OLE IDispatch a ser anexado ao COleDispatchDriver objeto.

bAutoRelease
Especifica se o despacho deve ser libertado quando este objeto sai do âmbito.

Observações

Esta função liberta qualquer IDispatch ponteiro que já esteja ligado ao COleDispatchDriver objeto.

Example

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 COleDispatchDriver objeto.

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

Parâmetros

lpDispatch
Apontador para um objeto OLE IDispatch a ser anexado ao COleDispatchDriver objeto.

bAutoRelease
Especifica se o despacho deve ser libertado quando este objeto sai do âmbito.

dispatchSrc
Referência a um objeto existente COleDispatchDriver .

Observações

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

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

A forma COleDispatchDriver( ) cria um COleDispatchDriver objeto mas não liga a IDispatch interface. Antes de usar COleDispatchDriver( ) sem argumentos, deve ligar-se IDispatch a ela usando o COleDispatchDriver::CreateDispatch ou o COleDispatchDriver::AttachDispatch. Para mais informações, consulte Implementar a Interface IDispatch.

Example

Veja o exemplo de COleDispatchDriver::CreateDispatch.

COleDispatchDriver::CreateDispatch

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

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

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

Parâmetros

CLSID
ID de classe do IDispatch objeto de ligação a criar.

pError
Apontar para um objeto de exceção OLE, que irá conter o código de estado resultante da criação.

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

Valor de retorno

Não-zero em termos de sucesso; caso contrário, 0.

Example

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

Desliga a ligação atual IDispatch deste objeto.

LPDISPATCH DetachDispatch();

Valor de retorno

Um apontador para o objeto OLE IDispatch previamente anexado.

Observações

O IDispatch não é divulgado.

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

Example

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver::GetProperty

Obtém a propriedade objeto especificada por dwDispID.

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

Parâmetros

dwDispID
Identifica a propriedade a recuperar.

vtProp
Especifica a propriedade a recuperar. Para possíveis valores, consulte a secção de Observações para COleDispatchDriver::InvokeHelper.

pvProp
Endereço da variável que irá receber o valor da propriedade. Deve corresponder ao tipo especificado pelo vtProp.

Example

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

COleDispatchDriver::InvokeHelper

Chama o método do objeto ou propriedade especificada 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 propriedade a ser invocada.

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

vtRet
Especifica o tipo do valor de retorno. Para valores possíveis, consulte a secção de Observações.

pvRet
Endereço da variável que irá receber o valor da propriedade ou devolver o valor. Deve corresponder ao tipo especificado pelo vtRet.

pbParamInfo
Apontador para uma cadeia de bytes terminada por nulo que especifica os tipos dos parâmetros após pbParamInfo.

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

Observações

O parâmetro pbParamInfo especifica os tipos de parâmetros passados ao método ou propriedade. A lista de variáveis de argumentos é representada por ... na declaração sintática.

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

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

Esta função converte os parâmetros para valores VARIANTARG e depois invoca o método IDispatch::Invoke . Se a chamada falhar Invoke , esta função lançará uma exceção. Se o SCODE (código de estado) devolvido por IDispatch::Invoke for DISP_E_EXCEPTION, esta função gera um objeto COleException ; caso contrário, gera um COleDispatchException.

Para mais informações, consulte VARIANTARG,Implementação da Interface IDispatch, IDispatch::Invoke e Estrutura dos Códigos de Erro COM no SDK do Windows.

Example

Veja o exemplo de COleDispatchDriver::CreateDispatch.

ColeDispatchDriver::m_bAutoRelease

Se for TRUE, o objeto COM acedido por m_lpDispatch será automaticamente libertado quando o ReleaseDispatch for chamado ou quando este COleDispatchDriver objeto for destruído.

BOOL m_bAutoRelease;

Observações

Por defeito, m_bAutoRelease está definido como TRUE no construtor.

Para mais informações sobre a libertação de objetos COM, consulte Implementing Reference Counting e IUnknown::Release no Windows SDK.

Example

// 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 IDispatch interface ligado a este COleDispatchDriver.

LPDISPATCH m_lpDispatch;

Observações

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

Para mais informações, consulte IDispatch no SDK do Windows.

Example

Veja o exemplo de COleDispatchDriver::AttachDispatch.

COleDispatchDriver::operator =

Copia o valor fonte para o COleDispatchDriver objeto.

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

Parâmetros

dispatchSrc
Um apontador para um objeto existente COleDispatchDriver .

COleDispatchDriver::operador LPDISPATCH

Acede ao ponteiro subjacente IDispatch do COleDispatchDriver objeto.

operator LPDISPATCH();

Example

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

Liberta a IDispatch ligação. Para mais informações, consulte Implementar a Interface IDispatch

void ReleaseDispatch();

Observações

Se a libertação automática estiver definida para esta ligação, esta função chama IDispatch::Release antes de libertar a interface.

Example

Veja 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 definir.

vtProp
Especifica o tipo de propriedade a definir. Para possíveis valores, consulte a secção de Observações para COleDispatchDriver::InvokeHelper.

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

Example

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

Consulte também

Exemplo MFC CALCDRIV
ACDUAL de Exemplo MFC
Gráfico de Hierarquia
Classe CCmdTarget