Mapas de conexiones

Los controles OLE pueden exponer interfaces a otras aplicaciones. Estas interfaces solo permiten el acceso desde un contenedor a ese control. Si un control OLE desea tener acceso a interfaces externas de otros objetos OLE, se debe establecer un punto de conexión. Este punto de conexión permite un control de acceso saliente a mapas de distribución externos, como mapas de eventos o funciones de notificación.

La biblioteca Microsoft Foundation Class ofrece un modelo de programación que admite puntos de conexión. En este modelo, se usan "mapas de conexión" para designar interfaces o puntos de conexión para el control OLE. Los mapas de conexión contienen una macro para cada punto de conexión. Para obtener más información sobre los mapas de conexión, consulte la CConnectionPoint clase .

Normalmente, un control admite solo dos puntos de conexión: uno para eventos y otro para las notificaciones de propiedades. Estas se implementan mediante la COleControl clase base y no requieren ningún trabajo adicional por parte del escritor de controles. Cualquier otro punto de conexión que quiera implementar en la clase debe agregarse manualmente. Para admitir mapas y puntos de conexión, MFC proporciona las macros siguientes:

Declaración y demarcación de mapa de conexión

Nombre	Descripción
BEGIN_CONNECTION_PART	Declara una clase incrustada que implementa un punto de conexión adicional (se debe usar en la declaración de clase).
END_CONNECTION_PART	Finaliza la declaración de un punto de conexión (se debe usar en la declaración de clase).
CONNECTION_IID	Especifica el identificador de interfaz del punto de conexión del control.
DECLARE_CONNECTION_MAP	Declara que se usará un mapa de conexión en una clase (se debe usar en la declaración de clase).
BEGIN_CONNECTION_MAP	Comienza la definición de un mapa de conexión (debe usarse en la implementación de la clase).
END_CONNECTION_MAP	Finaliza la definición de un mapa de conexión (debe usarse en la implementación de la clase).
CONNECTION_PART	Especifica un punto de conexión en el mapa de conexión del control.

Las siguientes funciones ayudan a un receptor a establecer y desconectar una conexión mediante puntos de conexión:

Inicialización y finalización de puntos de conexión

Nombre	Descripción
AfxConnectionAdvise	Establece una conexión entre un origen y un receptor.
AfxConnectionUnadvise	Interrumpe una conexión entre un origen y un receptor.

BEGIN_CONNECTION_PART

Use la BEGIN_CONNECTION_PART macro para comenzar la definición de puntos de conexión adicionales más allá de los puntos de conexión de notificación de eventos y propiedades.

BEGIN_CONNECTION_PART(theClass, localClass)

Parámetros

theClass Especifica el nombre de la clase de control cuyo punto de conexión es este.

localClass Especifica el nombre de la clase local que implementa el punto de conexión.

Comentarios

En el archivo de declaración (.h) que define las funciones miembro de la clase, inicie el punto de conexión con la BEGIN_CONNECTION_PART macro. A continuación, agregue la CONNECTION_IID macro y cualquier otra función miembro que desee implementar. Por último, complete el mapa del punto de conexión con la END_CONNECTION_PART macro.

Requisitos

Encabezado afxdisp.h

END_CONNECTION_PART

Finaliza la declaración del punto de conexión.

END_CONNECTION_PART(localClass)

Parámetros

localClass
Especifica el nombre de la clase local que implementa el punto de conexión.

Requisitos

Encabezado afxdisp.h

CONNECTION_IID

Use entre las BEGIN_CONNECTION_PART macros y END_CONNECTION_PART para definir un identificador de interfaz para un punto de conexión compatible con el control OLE.

CONNECTION_IID(iid)

Parámetros

iid
Identificador de interfaz de la interfaz a la que llama el punto de conexión.

Comentarios

El iid argumento es un identificador de interfaz que se usa para identificar la interfaz a la que llama el punto de conexión en sus receptores conectados. Por ejemplo:

CONNECTION_IID(IID_ISampleSink)

Especifica un punto de conexión que llama a la ISinkInterface interfaz.

Requisitos

Encabezado afxdisp.h

DECLARE_CONNECTION_MAP

Cada clase derivada de COleControl en el programa puede proporcionar un mapa de conexión para especificar puntos de conexión adicionales que admita el control.

DECLARE_CONNECTION_MAP()

Comentarios

Si el control admite puntos adicionales, use la DECLARE_CONNECTION_MAP macro al final de la declaración de clase. A continuación, en el archivo .cpp que define las funciones miembro de la clase , use la BEGIN_CONNECTION_MAP macro, CONNECTION_PART las macros para cada uno de los puntos de conexión del control y la END_CONNECTION_MAP macro para declarar el final del mapa de conexión.

Requisitos

Encabezado afxdisp.h

BEGIN_CONNECTION_MAP

Cada clase derivada de COleControl en el programa puede proporcionar un mapa de conexión para especificar puntos de conexión que admitirá el control.

BEGIN_CONNECTION_MAP(theClass, theBase)

Parámetros

theClass
Especifica el nombre de la clase de control cuyo punto de conexión es este.

theBase
Especifica el nombre de clase base de theClass.

Comentarios

En el archivo de implementación (.CPP) que define las funciones miembro de la clase, inicie el mapa de conexión con la BEGIN_CONNECTION_MAP macro y agregue entradas de macro para cada uno de los puntos de conexión mediante la CONNECTION_PART macro. Por último, complete el mapa de conexión con la END_CONNECTION_MAP macro.

Requisitos

Encabezado afxdisp.h

END_CONNECTION_MAP

Finaliza la definición del mapa de conexión.

END_CONNECTION_MAP()

Requisitos

Encabezado afxdisp.h

CONNECTION_PART

Asigna un punto de conexión para el control OLE a un identificador de interfaz específico.

CONNECTION_PART(theClass, iid, localClass)

Parámetros

theClass
Especifica el nombre de la clase de control cuyo punto de conexión es este.

iid
Identificador de interfaz de la interfaz a la que llama el punto de conexión.

localClass
Especifica el nombre de la clase local que implementa el punto de conexión.

Comentarios

Por ejemplo:

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

implementa un mapa de conexión, con un punto de conexión, que llama a la interfaz IID_ISinkInterface.

Requisitos

Encabezado afxdisp.h

AfxConnectionAdvise

Llame a esta función para establecer una conexión entre un origen, especificado por pUnkSrcy un receptor, especificado por pUnkSink.

BOOL AFXAPI AfxConnectionAdvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD FAR* pdwCookie);

Parámetros

pUnkSrc
Puntero al objeto que llama a la interfaz.

pUnkSink
Puntero al objeto que implementa la interfaz.

iid
Identificador de la interfaz de la conexión.

bRefCount
Para las conexiones fuera de proceso, este parámetro debe ser TRUEy indica que la creación de la conexión debe hacer que se incremente el recuento de referencias de pUnkSink .

En el caso de las conexiones en proceso, TRUE indica que la creación de la conexión debe hacer que se incremente el recuento de pUnkSink referencias. FALSE indica que no se debe incrementar el recuento de referencias.

Advertencia: En general, no se puede predecir qué conexiones están en proceso y qué conexiones están fuera de proceso, por lo que se recomienda establecer siempre este parámetro TRUEen .

pdwCookie
Puntero a un DWORD donde se devuelve un identificador de conexión. Este valor debe pasarse como parámetro dwCookie a AfxConnectionUnadvise al desconectar la conexión.

Valor devuelto

Distinto de cero si se estableció una conexión; de lo contrario, 0.

Ejemplo

//CMySink is a CCmdTarget-derived class supporting automation.
//Instantiate the sink class.
CMySink mysink;

//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Establish a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a cookie identifying the connection, and is needed
//to terminate this connection.
AfxConnectionAdvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, &dwCookie);

Requisitos

Encabezado: afxctl.h

AfxConnectionUnadvise

Llame a esta función para desconectar una conexión entre un origen, especificado por pUnkSrcy un receptor, especificado por pUnkSink.

BOOL AFXAPI AfxConnectionUnadvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD dwCookie);

Parámetros

pUnkSrc
Puntero al objeto que llama a la interfaz.

pUnkSink
Puntero al objeto que implementa la interfaz.

iid
Identificador de interfaz de la interfaz del punto de conexión.

bRefCount
En el caso de las conexiones fuera del proceso, este parámetro debe ser TRUEy indica que la creación de la conexión debe hacer que se decremente el recuento de referencias de pUnkSink .

En el caso de las conexiones en proceso, TRUE indica que la creación de la conexión debe provocar que se decremente el recuento de pUnkSink referencias. FALSE indica que no se debe disminuir el recuento de referencias.

Advertencia: En general, no se puede predecir qué conexiones están en proceso y qué conexiones están fuera de proceso, por lo que se recomienda establecer siempre este parámetro TRUEen .

dwCookie
Identificador de conexión devuelto por AfxConnectionAdvise.

Valor devuelto

Distinto de cero si se desconecta una conexión; de lo contrario, 0.

Ejemplo

//mysink is a CCmdTarget-derived class supporting automation.
//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Terminate a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a value obtained through AfxConnectionAdvise().
AfxConnectionUnadvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, dwCookie);

Requisitos

Encabezado: afxctl.h

Consulte también

Macros y globales