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
| Nombre | Descripción |
|---|---|
| CConnectionPoint::CConnectionPoint | Construye un objeto CConnectionPoint. |
Métodos públicos
| Nombre | Descripción |
|---|---|
| CConnectionPoint::GetConnections | Recupera todos los puntos de conexión de un mapa de conexiones. |
| CConnectionPoint::GetContainer | Recupera el contenedor del control que posee el mapa de conexiones. |
| CConnectionPoint::GetIID | Recupera el id. de interfaz de un punto de conexión. |
| CConnectionPoint::GetMaxConnections | Recupera el número máximo de puntos de conexión admitidos por un control. |
| CConnectionPoint::GetNextConnection | Recupera un puntero al elemento de conexión en pos. |
| CConnectionPoint::GetStartPosition | Inicia una iteración de mapa mediante la devolución de un valor POSITION que se puede pasar a una llamada a GetNextConnection. |
| CConnectionPoint::OnAdvise | Lo llama el marco al establecer o interrumpir las conexiones. |
| CConnectionPoint::QuerySinkInterface | Recupera un puntero a la interfaz receptora solicitada. |
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
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.