CConnectionPoint (clase)

Define un tipo especial de interfaz que se utiliza para comunicarse con otros objetos OLE, denominado "punto de conexión".

Sintaxis

class CConnectionPoint : public CCmdTarget

Miembros

Constructores públicos

Métodos públicos

Comentarios

A diferencia de las interfaces OLE normales, que se usan para implementar y exponer la funcionalidad de un control OLE, un punto de conexión implementa una interfaz saliente que puede iniciar acciones en otros objetos, como desencadenar eventos y notificaciones de cambio.

Una conexión consta de dos partes: el objeto que llama a la interfaz, denominado "origen" y el objeto que implementa la interfaz, denominado "receptor". Al exponer un punto de conexión, un origen permite a los receptores establecer conexiones a sí mismos. Mediante el mecanismo de punto de conexión, un objeto de origen obtiene un puntero a la implementación del receptor de un conjunto de funciones miembro. Por ejemplo, para desencadenar un evento implementado por el receptor, el origen puede llamar al método adecuado de la implementación del receptor.

De forma predeterminada, una clase derivada de COleControl implementa dos puntos de conexión: uno para eventos y otro para las notificaciones de cambio de propiedad. Estas conexiones se usan, respectivamente, para la activación de eventos y para notificar a un receptor (por ejemplo, el contenedor del control) cuando el valor de una propiedad ha cambiado. También se proporciona compatibilidad con los controles OLE para implementar puntos de conexión adicionales. Para cada punto de conexión adicional implementado en la clase de control, debe declarar un elemento de conexión que implemente el punto de conexión. Si implementa uno o varios puntos de conexión, también debe declarar un único "mapa de conexiones" en la clase de control.

En el ejemplo siguiente se muestra un mapa de conexiones simple y un punto de conexión para el control OLE Sample, que consta de dos fragmentos de código: la primera parte declara el mapa de conexiones y el punto; la segunda implementa este mapa y punto. El primer fragmento se inserta en la declaración de la clase de control, en la sección protected:

// Connection point for ISample interface
BEGIN_CONNECTION_PART(CMyClass, SampleConnPt)
CONNECTION_IID(IID_ISampleSink)
END_CONNECTION_PART(SampleConnPt)

DECLARE_CONNECTION_MAP()

Las macros BEGIN_CONNECTION_PART y END_CONNECTION_PART declaran una clase insertada, XSampleConnPt (derivada de CConnectionPoint), que implementa este punto de conexión determinado. Si quiere invalidar cualquier función miembro CConnectionPoint o agregar funciones miembro propias, declárelas entre estas dos macros. Por ejemplo, la macro CONNECTION_IID invalida la función miembro CConnectionPoint::GetIID cuando se coloca entre estas dos macros.

El segundo fragmento de código se inserta en el archivo de implementación (. CPP) de la clase de control. Este código implementa el mapa de conexiones, que incluye el punto de conexión adicional, SampleConnPt:

BEGIN_CONNECTION_MAP(CMyClass, CCmdTarget)
   CONNECTION_PART(CMyClass, IID_ISampleSink, SampleConnPt)
END_CONNECTION_MAP()

Una vez insertados estos fragmentos de código, el control OLE de ejemplo expone un punto de conexión para la interfaz ISampleSink.

Normalmente, los puntos de conexión admiten la "multidifusión", que es la capacidad de difundir a varios receptores conectados a la misma interfaz. En el siguiente fragmento de código se muestra cómo realizar la multidifusión mediante la iteración en cada receptor de un punto de conexión:

void CMyClass::CallSinkFunc()
{
   POSITION pos = m_xSampleConnPt.GetStartPosition();
   ISampleSink *pSampleSink;
   while (pos != NULL)
   {
      pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
      if (pSampleSink != NULL)
      {
         pSampleSink->SinkFunc();
      }
   }
}

En este ejemplo se recupera el conjunto actual de conexiones en el punto de conexión SampleConnPt con una llamada a CConnectionPoint::GetConnections. A continuación, itera por las conexiones y llama a ISampleSink::SinkFunc en cada conexión activa.

Para más información sobre cómo usar CConnectionPoint, consulte el artículo Puntos de conexión.

Jerarquía de herencia

CObject

CCmdTarget

CConnectionPoint

Requisitos

Encabezado: afxdisp.h

CConnectionPoint::CConnectionPoint

Construye un objeto CConnectionPoint.

CConnectionPoint();

CConnectionPoint::GetConnections

Llame a esta función para recuperar todas las conexiones activas de un punto de conexión.

const CPtrArray* GetConnections();

Valor devuelto

Puntero a una matriz de conexiones activas (receptores). Algunos de los punteros de la matriz pueden ser NULL. Cada puntero distinto de NULL de esta matriz se puede convertir de forma segura en un puntero a la interfaz receptora mediante un operador de conversión.

CConnectionPoint::GetContainer

Lo llama el marco para recuperar el IConnectionPointContainer para el punto de conexión.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Valor devuelto

Puntero al contenedor si es correcto; de lo contrario, NULL.

Comentarios

Normalmente, esta función se implementa mediante la macro BEGIN_CONNECTION_PART.

CConnectionPoint::GetIID

Llamada por el marco para recuperar el id. de interfaz de un punto de conexión.

virtual REFIID GetIID() = 0;

Valor devuelto

Referencia al id. de interfaz del punto de conexión.

Comentarios

Invalide esta función para devolver el id. de interfaz de este punto de conexión.

CConnectionPoint::GetMaxConnections

Llamado por el marco para recuperar el número máximo de conexiones admitido por el punto de conexión.

virtual int GetMaxConnections();

Valor devuelto

Número máximo de conexiones admitidas por el control o -1 si no hay límite.

Comentarios

La implementación predeterminada devuelve -1, lo que indica que no hay límite.

Invalide esta función si desea limitar el número de receptores que se pueden conectar al control.

CConnectionPoint::GetNextConnection

Recupera un puntero al elemento de conexión en pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parámetros

pos
Especifica una referencia a un valor POSITION devuelto por una llamada anterior GetNextConnection o GetStartPosition.

Valor devuelto

Puntero al elemento de conexión especificado por pos o NULL.

Comentarios

Esta función es más útil para recorrer en iteración todos los elementos del mapa de conexiones. Al iterar, omita los valores NULL devueltos por esta función.

Ejemplo

void CMyClass::CallSinkFunc()
{
   POSITION pos = m_xSampleConnPt.GetStartPosition();
   ISampleSink *pSampleSink;
   while (pos != NULL)
   {
      pSampleSink = (ISampleSink *)(m_xSampleConnPt.GetNextConnection(pos));
      if (pSampleSink != NULL)
      {
         pSampleSink->SinkFunc();
      }
   }
}

CConnectionPoint::GetStartPosition

Inicia una iteración de mapa mediante la devolución de un valor POSITION que se puede pasar a una llamada GetNextConnection.

POSITION GetStartPosition() const;

Valor devuelto

Valor POSITION que indica una posición inicial para iterar la asignación; o NULL si la asignación está vacía.

Comentarios

La secuencia de iteración no es predecible; por lo tanto, el «primer elemento de la asignación» no tiene importancia especial.

Ejemplo

Vea el ejemplo de CConnectionPoint::GetNextConnection.

CConnectionPoint::OnAdvise

Lo llama el marco cuando se establece o interrumpe una conexión.

virtual void OnAdvise(BOOL bAdvise);

Parámetros

bAdvise
TRUE, si se está estableciendo una conexión; en caso contrario, FALSE.

Comentarios

La implementación predeterminada no hace nada.

Invalide esta función si desea recibir notificaciones cuando los receptores se conecten o se desconecten del punto de conexión.

CConnectionPoint::QuerySinkInterface

Recupera un puntero a la interfaz receptora solicitada.

virtual HRESULT QuerySinkInterface(
    LPUNKNOWN pUnkSink,
    void** ppInterface);

Parámetros

pUnkSink
Identificador de la interfaz de receptor solicitada.

ppInterface
Puntero al puntero de interfaz identificado por pUnkSink. Si el objeto no admite esta interfaz, * ppInterface se establece como NULL.

Valor devuelto

Valor HRESULT estándar.

Consulte también

CCmdTarget (clase)
Gráfico de jerarquías