Clase COleDispatchDriver

Implementa el cliente de automatización OLE.

Sintaxis

class COleDispatchDriver

Miembros

Constructores públicos

Nombre	Descripción
COleDispatchDriver::COleDispatchDriver	Construye un objeto COleDispatchDriver.

Métodos públicos

Nombre	Descripción
COleDispatchDriver::AttachDispatch	Asocia una conexión IDispatch al objeto COleDispatchDriver.
COleDispatchDriver::CreateDispatch	Crea una conexión IDispatch y la asocia al objeto COleDispatchDriver.
COleDispatchDriver::DetachDispatch	Desasocia una conexión IDispatch, sin liberarla.
COleDispatchDriver::GetProperty	Obtiene una propiedad de automatización.
COleDispatchDriver::InvokeHelper	Asistente para llamar a métodos de automatización.
COleDispatchDriver::ReleaseDispatch	Libera una conexión IDispatch.
COleDispatchDriver::SetProperty	Establece una propiedad de automatización.

Operadores públicos

Nombre	Descripción
COleDispatchDriver::operator =	Copia el valor de origen en el objeto COleDispatchDriver.
COleDispatchDriver::operator LPDISPATCH	Accede al puntero subyacente IDispatch.

Miembros de datos públicos

Nombre	Descripción
COleDispatchDriver::m_bAutoRelease	Especifica si se va a liberar IDispatch durante ReleaseDispatch o la destrucción del objeto.
COleDispatchDriver::m_lpDispatch	Indica el puntero a la interfaz IDispatch asociada a este COleDispatchDriver.

Comentarios

COleDispatchDriver no tiene una clase base.

Las interfaces de envío OLE proporcionan acceso a los métodos y propiedades de un objeto. Las funciones miembro de COleDispatchDriver asocian, desasocian, crean y liberan una conexión de envío del tipo IDispatch. Otras funciones miembro usan listas de argumentos variables para simplificar la llamada a IDispatch::Invoke.

Esta clase se puede usar directamente, pero generalmente solo la usan las clases creadas mediante el Asistente para agregar clases. Cuando crea nuevas clases de C++ importando una biblioteca de tipos, las nuevas clases se derivan de COleDispatchDriver.

Para más información sobre el uso de COleDispatchDriver, consulte los siguientes artículos:

• Clientes de automatización

• Servidores de automatización

Jerarquía de herencia

COleDispatchDriver

Requisitos

Encabezado: afxdisp.h

COleDispatchDriver::AttachDispatch

Llame a la función miembro AttachDispatch para adjuntar un puntero IDispatch al objeto COleDispatchDriver . Para obtener más información, consulta Implementing the IDispatch Interface.

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

Parámetros

lpDispatch
Puntero a un objeto IDispatch OLE que se adjuntará al objeto COleDispatchDriver .

bAutoRelease
Especifica si el envío se liberará cuando este objeto se salga del ámbito.

Comentarios

Esta función libera cualquier puntero IDispatch que ya está conectado al objeto COleDispatchDriver .

Ejemplo

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

Construye un objeto COleDispatchDriver.

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

Parámetros

lpDispatch
Puntero a un objeto IDispatch OLE que se adjuntará al objeto COleDispatchDriver .

bAutoRelease
Especifica si el envío se liberará cuando este objeto se salga del ámbito.

dispatchSrc
Referencia a un objeto COleDispatchDriver existente.

Comentarios

El formulario COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) conecta la interfaz IDispatch.

El formulario COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) copia un objeto COleDispatchDriver existente e incrementa el recuento de referencias.

El formulario COleDispatchDriver( ) crea un objeto COleDispatchDriver pero no conecta la interfaz IDispatch. Antes de usar COleDispatchDriver( ) sin argumentos, debe conectar IDispatch a él mediante COleDispatchDriver::CreateDispatch o COleDispatchDriver::AttachDispatch. Para obtener más información, consulta Implementing the IDispatch Interface.

Ejemplo

Vea el ejemplo de COleDispatchDriver::CreateDispatch.

COleDispatchDriver::CreateDispatch

Crea un objeto de interfaz IDispatch y lo vincula al objeto COleDispatchDriver .

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

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

Parámetros

clsid
Id. de clase del objeto de conexión IDispatch que se va a crear.

pError
Puntero a un objeto de excepción OLE, que contendrá el código de estado resultante de la creación.

lpszProgID
Puntero al identificador de programación (por ejemplo, "Excel.Document.5") del objeto de automatización para el que es necesario crear el objeto de envío.

Valor devuelto

Distinto de cero en caso de éxito; en caso contrario, es 0.

Ejemplo

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

Desasocia la conexión IDispatch actual de este objeto.

LPDISPATCH DetachDispatch();

Valor devuelto

Puntero al objeto IDispatch OLE asociado anteriormente.

Comentarios

IDispatch no se libera.

Para más información sobre el tipo LPDISPATCH, consulte Implementación de la interfaz IDispatch en Windows SDK.

Ejemplo

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver::GetProperty

Obtiene la propiedad de objeto especificada por dwDispID.

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

Parámetros

dwDispID
Identifica la propiedad que se va a recuperar.

vtProp
Especifica la propiedad que se va a recuperar. Para los valores posibles, vea la sección Comentarios para COleDispatchDriver::InvokeHelper.

pvProp
Dirección de la variable que recibirá el valor de la propiedad. Debe coincidir con el tipo especificado por vtProp.

Ejemplo

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

COleDispatchDriver::InvokeHelper

Llama a la propiedad o al método de objeto especificados por dwDispID, en el contexto especificado por wFlags.

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

Parámetros

dwDispID
Identifica el método o la propiedad que se va a invocar.

wFlags
Las marcas que describen el contexto de la llamada a IDispatch::Invoke. . Para una lista de valores posibles, consulte el parámetro wFlags en IDispatch::Invoke en Windows SDK.

vtRet
Especifica el tipo del valor devuelto. Para los valores posibles, vea la sección Comentarios.

pvRet
Dirección de la variable que recibirá el valor de la propiedad o el valor devuelto. Debe coincidir con el tipo especificado por vtRet.

pbParamInfo
Puntero a una cadena terminada en null de bytes que especifica los tipos de los parámetros que siguen a pbParamInfo.

...
Lista de variables de parámetros, de tipos especificados en pbParamInfo.

Comentarios

El parámetro pbParamInfo especifica los tipos de los parámetros pasados al método o a la propiedad. La lista variable de argumentos se representa mediante ... en la declaración de sintaxis.

Los valores posibles del argumento vtRet se toman de la enumeración VARENUM. Los valores posibles son los siguientes:

Símbolo	Tipo devuelto
VT_EMPTY	void
VT_I2	short
VT_I4	long
VT_R4	float
VT_R8	double
VT_CY	CY
VT_DATE	FECHA
VT_BSTR	BSTR
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_VARIANT	VARIANT
VT_UNKNOWN	LPUNKNOWN

El argumento pbParamInfo es una lista separada por espacios de constantes VTS_. Uno o varios de estos valores, separados por espacios (no por comas), especifican la lista de parámetros de la función. Los valores posibles se muestran con la macro EVENT_CUSTOM .

Esta función convierte los parámetros en valores VARIANTARG y, a continuación, invoca el método IDispatch::Invoke . Si se produce un error en la llamada a Invoke , esta función generará una excepción. Si SCODE (código de estado) devuelto por IDispatch::Invoke es DISP_E_EXCEPTION, esta función generará un objeto COleException; de lo contrario, generará una COleDispatchException.

Para más información, consulte VARIANTARG, Implementación de la interfaz IDispatch, IDispatch:: Invoke y Estructura de códigos de error de COM en Windows SDK.

Ejemplo

Vea el ejemplo de COleDispatchDriver::CreateDispatch.

COleDispatchDriver::m_bAutoRelease

Si es TRUE, el objeto COM al que accede mediante m_lpDispatch se liberará automáticamente cuando se llame a ReleaseDispatch o cuando se destruya este objeto COleDispatchDriver.

BOOL m_bAutoRelease;

Comentarios

De forma predeterminada, m_bAutoRelease se establece en TRUE en el constructor.

Para más información sobre cómo liberar objetos COM, consulte Implementación del recuento de referencias e IUnknown::Release en Windows SDK.

Ejemplo

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

Indica el puntero a la interfaz IDispatch asociada a este COleDispatchDriver.

LPDISPATCH m_lpDispatch;

Comentarios

El miembro de datos m_lpDispatch es una variable pública del tipo LPDISPATCH.

Para más información, consulte IDispatch en Windows SDK.

Ejemplo

Consulte el ejemplo de COleDispatchDriver::AttachDispatch.

COleDispatchDriver::operator =

Copia el valor de origen en el objeto COleDispatchDriver.

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

Parámetros

dispatchSrc
Un puntero a un objeto COleDispatchDriver existente.

COleDispatchDriver::operator LPDISPATCH

Accede al puntero IDispatch subyacente del objeto COleDispatchDriver.

operator LPDISPATCH();

Ejemplo

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 la conexión IDispatch. Para más información, consulte Implementación de la interfaz IDispatch.

void ReleaseDispatch();

Comentarios

Si se ha establecido la versión automática para esta conexión, esta función llama a IDispatch::Release antes de liberar la interfaz.

Ejemplo

Consulte el ejemplo de COleDispatchDriver::AttachDispatch.

COleDispatchDriver::SetProperty

Establece la propiedad de objeto OLE especificada por dwDispID.

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

Parámetros

dwDispID
Identifica la propiedad que se va a establecer.

vtProp
Especifica el tipo de la propiedad que se va a establecer. Para los valores posibles, vea la sección Comentarios para COleDispatchDriver::InvokeHelper.

...
Un parámetro único del tipo especificado por vtProp.

Ejemplo

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

Vea también

MFC Sample CALCDRIV
MFC Sample ACDUAL
Gráfico de jerarquías
CCmdTarget (clase)