Mapas de conexão

Os controles OLE são capazes de expor interfaces a outros aplicativos. Essas interfaces permitem apenas o acesso de um contêiner a esse controle. Se um controle OLE quiser acessar interfaces externas de outros objetos OLE, um ponto de conexão deverá ser estabelecido. Esse ponto de conexão permite um acesso de saída de controle a mapas de expedição externos, como mapas de eventos ou funções de notificação.

A biblioteca Microsoft Foundation Class oferece um modelo de programação que dá suporte a pontos de conexão. Nesse modelo, os "mapas de conexão" são usados para designar interfaces ou pontos de conexão para o controle OLE. Os mapas de conexão contêm uma macro para cada ponto de conexão. Para obter mais informações sobre mapas de conexão, consulte a CConnectionPoint classe.

Normalmente, um controle dá suporte a apenas dois pontos de conexão: um para eventos e outro para notificações de propriedade. Eles são implementados pela COleControl classe base e não exigem nenhum trabalho extra do gravador de controle. Quaisquer outros pontos de conexão que você deseja implementar em sua classe devem ser adicionados manualmente. Para dar suporte a mapas e pontos de conexão, o MFC fornece as seguintes macros:

Declaração e demarcação do Mapa de Conexão

Nome	Descrição
BEGIN_CONNECTION_PART	Declara uma classe inserida que implementa um ponto de conexão adicional (deve ser usado na declaração de classe).
END_CONNECTION_PART	Encerra a declaração de um ponto de conexão (deve ser usada na declaração de classe).
CONNECTION_IID	Especifica a ID da interface do ponto de conexão do controle.
DECLARE_CONNECTION_MAP	Declara que um mapa de conexão será usado em uma classe (deve ser usado na declaração de classe).
BEGIN_CONNECTION_MAP	Inicia a definição de um mapa de conexão (deve ser usado na implementação da classe).
END_CONNECTION_MAP	Finaliza a definição de um mapa de conexão (deve ser usado na implementação da classe).
CONNECTION_PART	Especifica um ponto de conexão no mapa de conexão do controle.

As seguintes funções ajudam um coletor a estabelecer e desconectar uma conexão usando pontos de conexão:

Inicialização/terminação de pontos de conexão

Nome	Descrição
AfxConnectionAdvise	Estabelece uma conexão entre uma fonte e um coletor.
AfxConnectionUnadvise	Interrompe uma conexão entre uma fonte e um coletor.

BEGIN_CONNECTION_PART

Use a BEGIN_CONNECTION_PART macro para iniciar a definição de pontos de conexão adicionais além dos pontos de conexão de notificação de eventos e propriedades.

BEGIN_CONNECTION_PART(theClass, localClass)

Parâmetros

theClass Especifica o nome da classe de controle cujo ponto de conexão é esse.

localClass Especifica o nome da classe local que implementa o ponto de conexão.

Comentários

No arquivo de declaração (.h) que define as funções de membro para sua classe, inicie o ponto de conexão com a BEGIN_CONNECTION_PART macro. Em seguida, adicione a CONNECTION_IID macro e quaisquer outras funções de membro que você deseja implementar. Por fim, preencha o mapa do ponto de conexão com a END_CONNECTION_PART macro.

Requisitos

Cabeçalho afxdisp.h

END_CONNECTION_PART

Encerra a declaração do ponto de conexão.

END_CONNECTION_PART(localClass)

Parâmetros

localClass
Especifica o nome da classe local que implementa o ponto de conexão.

Requisitos

Cabeçalho afxdisp.h

CONNECTION_IID

Use entre as BEGIN_CONNECTION_PART macros e END_CONNECTION_PART para definir uma ID de interface para um ponto de conexão com suporte do controle OLE.

CONNECTION_IID(iid)

Parâmetros

iid
A ID da interface chamada pelo ponto de conexão.

Comentários

O iid argumento é uma ID de interface usada para identificar a interface que o ponto de conexão chama em seus coletores conectados. Por exemplo:

CONNECTION_IID(IID_ISampleSink)

Especifica um ponto de conexão que chama a ISinkInterface interface.

Requisitos

Cabeçalho afxdisp.h

DECLARE_CONNECTION_MAP

Cada classe COleControl-derivada em seu programa pode fornecer um mapa de conexão para especificar pontos de conexão adicionais compatíveis com o controle.

DECLARE_CONNECTION_MAP()

Comentários

Se o controle der suporte a pontos adicionais, use a DECLARE_CONNECTION_MAP macro no final da declaração de classe. Em seguida, no arquivo .cpp que define as funções de membro para a classe, use a macro, CONNECTION_PART as BEGIN_CONNECTION_MAP macros para cada um dos pontos de conexão do controle e a END_CONNECTION_MAP macro para declarar o final do mapa de conexão.

Requisitos

Cabeçalho afxdisp.h

BEGIN_CONNECTION_MAP

Cada classe COleControl-derivada em seu programa pode fornecer um mapa de conexão para especificar pontos de conexão que seu controle dará suporte.

BEGIN_CONNECTION_MAP(theClass, theBase)

Parâmetros

theClass
Especifica o nome da classe de controle cujo mapa de conexão é esse.

theBase
Especifica o nome da classe base de theClass.

Comentários

No arquivo de implementação (.CPP) que define as funções de membro para sua classe, inicie o mapa de conexão com a BEGIN_CONNECTION_MAP macro e, em seguida, adicione entradas de macro para cada um dos pontos de conexão usando a CONNECTION_PART macro. Por fim, complete o mapa de conexão com a END_CONNECTION_MAP macro.

Requisitos

Cabeçalho afxdisp.h

END_CONNECTION_MAP

Encerra a definição do mapa de conexão.

END_CONNECTION_MAP()

Requisitos

Cabeçalho afxdisp.h

CONNECTION_PART

Mapeia um ponto de conexão para o controle OLE para uma ID de interface específica.

CONNECTION_PART(theClass, iid, localClass)

Parâmetros

theClass
Especifica o nome da classe de controle cujo ponto de conexão é esse.

iid
A ID da interface chamada pelo ponto de conexão.

localClass
Especifica o nome da classe local que implementa o ponto de conexão.

Comentários

Por exemplo:

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

implementa um mapa de conexão, com um ponto de conexão, que chama a interface IID_ISinkInterface.

Requisitos

Cabeçalho afxdisp.h

AfxConnectionAdvise

Chame essa função para estabelecer uma conexão entre uma origem, especificada por pUnkSrc, e um coletor, especificado por pUnkSink.

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

Parâmetros

pUnkSrc
Um ponteiro para o objeto que chama a interface.

pUnkSink
Um ponteiro para o objeto que implementa a interface.

iid
A ID da interface da conexão.

bRefCount
Para conexões fora do processo, esse parâmetro deve ser TRUE, e indica que a criação da conexão deve fazer com que a contagem de referência de pUnkSink seja incrementada.

Para conexões em processo, TRUE indica que a criação da conexão deve fazer com que a contagem de referência de pUnkSink seja incrementada. FALSE indica que a contagem de referência não deve ser incrementada.

Aviso: Em geral, não é possível prever quais conexões estão em processo e quais conexões estão fora do processo, portanto, é recomendável sempre definir esse parâmetro como TRUE.

pdwCookie
Um ponteiro para um DWORD em que um identificador de conexão é retornado. Esse valor deve ser passado como dwCookie parâmetro para AfxConnectionUnadvise ao desconectar a conexão.

Valor de retorno

Não zero se uma conexão foi estabelecida, caso contrário, 0.

Exemplo

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

Cabeçalho: afxctl.h

AfxConnectionUnadvise

Chame essa função para desconectar uma conexão entre uma origem, especificada por pUnkSrc, e um coletor, especificado por pUnkSink.

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

Parâmetros

pUnkSrc
Um ponteiro para o objeto que chama a interface.

pUnkSink
Um ponteiro para o objeto que implementa a interface.

iid
A ID da interface do ponto de conexão.

bRefCount
Para conexões fora do processo, esse parâmetro deve ser TRUE, e indica que a criação da conexão deve fazer com que a contagem de referência de pUnkSink seja diminuída.

Para conexões em processo, TRUE indica que a criação da conexão deve fazer com que a contagem de referência de pUnkSink seja diminuída. FALSE indica que a contagem de referência não deve ser diminuída.

Aviso: Em geral, não é possível prever quais conexões estão em processo e quais conexões estão fora do processo, portanto, é recomendável sempre definir esse parâmetro como TRUE.

dwCookie
O identificador de conexão retornado por AfxConnectionAdvise.

Valor retornado

Não zero se uma conexão foi desconectada, caso contrário, 0.

Exemplo

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

Cabeçalho: afxctl.h

Confira também

Macros e Globais