Classe CConnectionPoint

Define um tipo especial de interface usado para se comunicar com outros objetos OLE, chamado de "ponto de conexão".

Sintaxe

class CConnectionPoint : public CCmdTarget

Membros

Construtores públicos

Nome	Descrição
CConnectionPoint::CConnectionPoint	Constrói um objeto CConnectionPoint.

Métodos públicos

Nome	Descrição
CConnectionPoint::GetConnections	Recupera todos os pontos de conexão em um mapa de conexão.
CConnectionPoint::GetContainer	Recupera o contêiner do controle que detém o mapa de conexão.
CConnectionPoint::GetIID	Recupera a ID da interface de um ponto de conexão.
CConnectionPoint::GetMaxConnections	Recupera o número máximo de pontos de conexão com suporte em um controle.
CConnectionPoint::GetNextConnection	Recupera um ponteiro para o elemento de conexão em pos.
CConnectionPoint::GetStartPosition	Inicia uma iteração de mapa retornando um valor POSITION que pode ser passado para uma chamada GetNextConnection.
CConnectionPoint::OnAdvise	Chamado pela estrutura ao estabelecer ou interromper conexões.
CConnectionPoint::QuerySinkInterface	Recupera um ponteiro para a interface do coletor solicitada.

Comentários

Ao contrário das interfaces OLE normais, que são usadas para implementar e expor a funcionalidade de um controle OLE, um ponto de conexão implementa uma interface de saída capaz de iniciar ações em outros objetos, como disparar eventos e alterar notificações.

Uma conexão consiste em duas partes: o objeto que chama a interface, chamado de "origem" e o objeto que implementa a interface, chamado de "coletor". Ao expor um ponto de conexão, uma fonte permite que os coletores estabeleçam conexões para si mesmos. Por meio do mecanismo de ponto de conexão, um objeto de origem obtém um ponteiro para a implementação do coletor de um conjunto de funções de membro. Por exemplo, para disparar um evento implementado pelo coletor, a origem pode chamar o método apropriado da implementação do coletor.

Por padrão, uma classe derivada de COleControl implementa dois pontos de conexão: um para eventos e outro para notificações de alteração de propriedade. Essas conexões são usadas, respectivamente, para disparo de eventos e para notificar um coletor (por exemplo, o contêiner do controle) quando um valor da propriedade foi alterado. Também há suporte para fornecido para controles OLE implementarem pontos de conexão adicionais. Para cada ponto de conexão adicional implementado em sua classe de controle, você deve declarar uma "parte de conexão" que implementa o ponto de conexão. Se você implementar um ou mais pontos de conexão, também precisará declarar um só "mapa de conexão" em sua classe de controle.

O exemplo a seguir demonstra um mapa de conexão simples e um ponto de conexão para o controle OLE Sample, que consiste em dois fragmentos de código: a primeira parte declara o mapa e o ponto de conexão; a segunda implementa esse mapa e ponto. O primeiro fragmento é inserido na declaração da classe de controle, na seção protected:

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

DECLARE_CONNECTION_MAP()

As macros BEGIN_CONNECTION_PART e END_CONNECTION_PART declaram uma classe inserida, XSampleConnPt (derivada de CConnectionPoint) que implementa esse ponto de conexão específico. Se você quiser substituir qualquer função de membro CConnectionPoint ou adicionar funções de membro próprias, declare-as entre essas duas macros. Por exemplo, a macro CONNECTION_IID substitui a função de membro CConnectionPoint::GetIID quando colocada entre essas duas macros.

O segundo fragmento de código é inserido no arquivo de implementação (.CPP) da classe de controle. Esse código implementa o mapa de conexão, que inclui o ponto de conexão adicional: SampleConnPt

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

Depois que esses fragmentos de código são inseridos, o controle OLE de exemplo expõe um ponto de conexão para a interface ISampleSink.

Normalmente, os pontos de conexão dão suporte a "multicasting", que é a capacidade de difusão para vários coletores conectados à mesma interface. O seguinte fragmento de código demonstra como realizar multicasting iterando em cada coletor em um ponto de conexão:

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

Este exemplo recupera o conjunto atual de conexões no ponto de conexão SampleConnPt com uma chamada para CConnectionPoint::GetConnections. Em seguida, itera pelas conexões e chama ISampleSink::SinkFunc em todas as conexões ativas.

Para mais informações sobre como usar CConnectionPoint, confira o artigo Pontos de Conexão.

Hierarquia de herança

CObject

CCmdTarget

CConnectionPoint

Requisitos

Cabeçalho afxdisp.h

CConnectionPoint::CConnectionPoint

Constrói um objeto CConnectionPoint.

CConnectionPoint();

CConnectionPoint::GetConnections

Chame essa função para recuperar todas as conexões ativas para um ponto de conexão.

const CPtrArray* GetConnections();

Valor de retorno

Um ponteiro para uma matriz de conexões ativas (coletores). Alguns dos ponteiros na matriz podem ser NULL. Cada ponteiro não NULL nessa matriz pode ser convertido com segurança em um ponteiro para a interface do coletor usando um operador de conversão.

CConnectionPoint::GetContainer

Chamado pela estrutura para recuperar o ponto de conexão IConnectionPointContainer.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Valor de retorno

Se tiver êxito, um ponteiro para o contêiner; caso contrário, NULL.

Comentários

Essa função normalmente é implementada pela macro BEGIN_CONNECTION_PART.

CConnectionPoint::GetIID

Chamada pela estrutura para recuperar a ID da interface de um ponto de conexão.

virtual REFIID GetIID() = 0;

Valor de retorno

Uma referência à ID da interface do ponto de conexão.

Comentários

Substitua essa função para retornar a ID da interface para esse ponto de conexão.

CConnectionPoint::GetMaxConnections

Chamada pela estrutura para recuperar o número máximo de conexões compatíveis com o ponto de conexão.

virtual int GetMaxConnections();

Valor de retorno

O número máximo de conexões compatíveis com o controle ou -1 se não houver limite.

Comentários

A implementação padrão retorna -1, indicando que não há limite.

Substitua essa função se você quiser limitar o número de coletores que podem se conectar ao seu controle.

CConnectionPoint::GetNextConnection

Recupera um ponteiro para o elemento de conexão em pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parâmetros

pos
Especifica uma referência a um valor POSITION retornado por uma chamada GetNextConnection ou GetStartPosition anterior.

Valor de retorno

Um ponteiro para o elemento de conexão especificado por pos ou NULL.

Comentários

Essa função é mais útil para iterar todos os elementos no mapa de conexão. Ao iterar, ignore todos os NULLs retornados dessa função.

Exemplo

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 uma iteração de mapa retornando um valor POSITION que pode ser passado para uma chamada GetNextConnection.

POSITION GetStartPosition() const;

Valor de retorno

Um valor POSITION que indica uma posição inicial para iterar o mapa; ou NULL se o mapa estiver vazio.

Comentários

A sequência de iteração não é previsível; portanto, o "primeiro elemento no mapa" não tem significado especial.

Exemplo

Confira o exemplo de CConnectionPoint::GetNextConnection.

CConnectionPoint::OnAdvise

Chamado pela estrutura quando uma conexão está sendo estabelecida ou interrompida.

virtual void OnAdvise(BOOL bAdvise);

Parâmetros

bAdvise
TRUE, se uma conexão estiver sendo estabelecida; caso contrário, FALSE.

Comentários

A implementação padrão não tem ação.

Substitua essa função se você quiser notificação quando os coletores se conectarem ou se desconectarem do ponto de conexão.

CConnectionPoint::QuerySinkInterface

Recupera um ponteiro para a interface do coletor solicitada.

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

Parâmetros

pUnkSink
O identificador da interface do coletor que está sendo solicitada.

ppInterface
Um ponteiro para o ponteiro da interface identificado por pUnkSink. Se o objeto não der suporte a essa interface, * ppInterface será definida como NULL.

Valor de retorno

Um valor HRESULT padrão.

Confira também

Classe CCmdTarget
Gráfico da hierarquia