Classe CConnectionPoint

Define um tipo especial de interface usada para comunicar com outros objetos OLE, chamada de "ponto de ligação".

Sintaxe

class CConnectionPoint : public CCmdTarget

Membros

Construtores Públicos

Métodos Públicos

Observações

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

Uma ligação consiste em duas partes: o objeto que chama a interface, chamado "fonte", e o objeto que implementa a interface, chamado "sumidour". Ao expor um ponto de ligação, uma fonte permite que os sumidouros estabeleçam ligações consigo próprias. Através do mecanismo do ponto de ligação, um objeto fonte obtém um ponteiro para a implementação do sumidouro de um conjunto de funções membros. Por exemplo, para lançar um evento implementado pelo sumidouro, a fonte pode chamar o método apropriado da implementação do sumidour.

Por defeito, uma COleControlclasse -derivada implementa dois pontos de ligação: um para eventos e outro para notificações de alteração de propriedade. Estas ligações são usadas, respetivamente, para disparo de eventos e para notificar um sumidouro (por exemplo, o contentor do controlo) quando o valor de uma propriedade mudou. É também fornecido suporte para controlos OLE implementarem pontos de ligação adicionais. Para cada ponto de ligação adicional implementado na sua classe de controlo, deve declarar uma "parte de ligação" que implemente o ponto de ligação. Se implementares um ou mais pontos de ligação, também precisas de declarar um único "mapa de ligação" na tua classe de controlo.

O exemplo seguinte demonstra um mapa de ligação simples e um ponto de ligação para o controlo Sample OLE, consistindo em dois fragmentos de código: a primeira parte declara o mapa de ligação e o ponto; a segunda implementa este mapa e ponto. O primeiro fragmento é inserido na declaração da classe de controlo, na protected secção:

// 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 embutida ( XSampleConnPt derivada de CConnectionPoint) que implementa este ponto de ligação em particular. Se quiseres sobrepor alguma CConnectionPoint função membro, ou adicionar funções membros tuas, declara-as entre estas duas macros. Por exemplo, a macro CONNECTION_IID sobrepõe-se à CConnectionPoint::GetIID função membro quando colocada entre estas duas macros.

O segundo fragmento de código é inserido no ficheiro de implementação (. CPP) da sua classe de controlo. Este código implementa o mapa de ligação, que inclui o ponto de ligação adicional, SampleConnPt:

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

Depois de inseridos estes fragmentos de código, o controlo OLE de exemplo expõe um ponto de ligação para a ISampleSink interface.

Normalmente, os pontos de ligação suportam "multicasting", que é a capacidade de transmitir para múltiplos sinks ligados à mesma interface. O seguinte fragmento de código demonstra como realizar multicasting iterando por cada pila num ponto de ligaçã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 ligações no SampleConnPt ponto de ligação com uma chamada para CConnectionPoint::GetConnections. Depois, ele percorre as ligações e as chamadas ISampleSink::SinkFunc em todas as ligações ativas.

Para mais informações sobre a utilização CConnectionPointde , consulte o artigo Pontos de Ligação.

Hierarquia de herança

CObject

CCmdTarget

CConnectionPoint

Requerimentos

Cabeçalho: afxdisp.h

CConnectionPoint::CConnectionPoint

Constrói um CConnectionPoint objeto.

CConnectionPoint();

CConnectionPoint::GetConnections.

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

const CPtrArray* GetConnections();

Valor de retorno

Um apontador para um array de ligações ativas (sinks). Alguns dos ponteiros no array podem ser NULL. Cada ponteiro não-NULL neste array pode ser convertido em segurança num ponteiro para a interface do sink usando um operador cast.

CConnectionPoint::GetContainer

Chamado pelo framework para recuperar o IConnectionPointContainer para o ponto de ligação.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Valor de retorno

Se for bem-sucedido, um apontador para o contentor; caso contrário, NULL.

Observações

Esta função é tipicamente implementada pelo BEGIN_CONNECTION_PART macro.

CConnectionPoint::GetIID

Chamada pela framework para recuperar o ID da interface de um ponto de ligação.

virtual REFIID GetIID() = 0;

Valor de retorno

Uma referência ao ID da interface do ponto de ligação.

Observações

Substitua esta função para devolver o ID da interface para este ponto de ligação.

CConnectionPoint::GetMaxConnections

Chamado pelo framework para recuperar o número máximo de ligações suportadas pelo ponto de ligação.

virtual int GetMaxConnections();

Valor de retorno

O número máximo de ligações suportadas pelo controlo, ou -1 se não houver limite.

Observações

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

Anule esta função se quiser limitar o número de pias que podem ligar ao seu controlo.

CConnectionPoint::ObtenhaNextConexão

Recupera um ponteiro para o elemento de ligação em pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parâmetros

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

Valor de retorno

Um ponteiro para o elemento de ligação especificado por pos, ou NULL.

Observações

Esta função é mais útil para iterar por todos os elementos do mapa de conexão. Ao iterar, ignore quaisquer NULLs devolvidos desta função.

Example

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::ObterInícioPosição

Inicia uma iteração do mapa ao devolver 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.

Observações

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

Example

Veja o exemplo de CConnectionPoint::GetNextConnection.

CConnectionPoint::OnAdvise

Chamada pelo framework quando uma ligação está a ser estabelecida ou quebrada.

virtual void OnAdvise(BOOL bAdvise);

Parâmetros

bAdvise
VERDADE, se estiver a ser estabelecida uma ligação; caso contrário, FALSO.

Observações

A implementação padrão não faz nada.

Substitua esta função se quiseres ser notificado quando os sinks ligam-se ou desligam-se do teu ponto de ligação.

CConnectionPoint::QuerySinkInterface

Recupera um ponteiro para a interface de atenuação solicitada.

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

Parâmetros

pUnkSink
O identificador da interface do sink que está a ser solicitado.

ppInterface
Um ponteiro para o ponteiro de interface identificado por pUnkSink. Se o objeto não suportar esta interface, * ppInterface é definido como NULL.

Valor de retorno

Um valor HRESULT padrão.

Consulte também

Classe CCmdTarget
Gráfico de Hierarquia