Classe CConnectionPoint

Definisce un tipo speciale di interfaccia utilizzata per comunicare con altri oggetti OLE, denominata "punto di connessione".

Sintassi

class CConnectionPoint : public CCmdTarget

Membri

Costruttori pubblici

Metodi pubblici

Osservazioni:

A differenza delle normali interfacce OLE, usate per implementare ed esporre la funzionalità di un controllo OLE, un punto di connessione implementa un'interfaccia in uscita in grado di avviare azioni su altri oggetti, ad esempio la generazione di eventi e le notifiche di modifica.

Una connessione è costituita da due parti: l'oggetto che chiama l'interfaccia, denominata "origine" e l'oggetto che implementa l'interfaccia, denominata "sink". Esponendo un punto di connessione, un'origine consente ai sink di stabilire connessioni a se stesso. Tramite il meccanismo del punto di connessione, un oggetto di origine ottiene un puntatore all'implementazione del sink di un set di funzioni membro. Ad esempio, per generare un evento implementato dal sink, l'origine può chiamare il metodo appropriato dell'implementazione del sink.

Per impostazione predefinita, una COleControlclasse derivata da -implementa due punti di connessione: uno per gli eventi e uno per le notifiche di modifica delle proprietà. Queste connessioni vengono usate, rispettivamente, per la generazione di eventi e per notificare un sink (ad esempio, il contenitore del controllo) quando un valore della proprietà è stato modificato. Viene inoltre fornito il supporto per i controlli OLE per implementare punti di connessione aggiuntivi. Per ogni punto di connessione aggiuntivo implementato nella classe di controllo, è necessario dichiarare una "parte di connessione" che implementa il punto di connessione. Se si implementano uno o più punti di connessione, è anche necessario dichiarare una singola "mappa di connessione" nella classe di controllo.

Nell'esempio seguente viene illustrata una semplice mappa di connessione e un punto di connessione per il Sample controllo OLE, costituito da due frammenti di codice: la prima parte dichiara la mappa di connessione e il punto. La seconda implementa la mappa e il punto. Il primo frammento viene inserito nella dichiarazione della classe del controllo, nella protected sezione :

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

DECLARE_CONNECTION_MAP()

Le macro BEGIN_CONNECTION_PART e END_CONNECTION_PART dichiarano una classe incorporata ( XSampleConnPt derivata da CConnectionPoint) che implementa questo particolare punto di connessione. Se si desidera eseguire l'override di qualsiasi CConnectionPoint funzione membro o aggiungere funzioni membro personalizzate, dichiararle tra queste due macro. Ad esempio, la macro CONNECTION_IID esegue l'override della CConnectionPoint::GetIID funzione membro quando viene posizionata tra queste due macro.

Il secondo frammento di codice viene inserito nel file di implementazione (. CPP) della classe di controllo. Questo codice implementa la mappa di connessione, che include il punto di connessione aggiuntivo, SampleConnPt:

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

Dopo l'inserimento di questi frammenti di codice, il controllo OLE di esempio espone un punto di connessione per l'interfaccia ISampleSink .

In genere, i punti di connessione supportano il "multicast", ovvero la possibilità di trasmettere a più sink connessi alla stessa interfaccia. Il frammento di codice seguente illustra come eseguire il multicast eseguendo l'iterazione di ogni sink in un punto di connessione:

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

In questo esempio viene recuperato il set corrente di connessioni nel SampleConnPt punto di connessione con una chiamata a CConnectionPoint::GetConnections. Scorre quindi le connessioni e chiama ISampleSink::SinkFunc su ogni connessione attiva.

Per altre informazioni sull'uso CConnectionPointdi , vedere l'articolo Punti di connessione.

Gerarchia di ereditarietà

CObject

CCmdTarget

CConnectionPoint

Requisiti

Intestazione: afxdisp.h

CConnectionPoint::CConnectionPoint

Costruisce un oggetto CConnectionPoint.

CConnectionPoint();

CConnectionPoint::GetConnections

Chiamare questa funzione per recuperare tutte le connessioni attive per un punto di connessione.

const CPtrArray* GetConnections();

Valore restituito

Puntatore a una matrice di connessioni attive (sink). Alcuni puntatori nella matrice possono essere NULL. Ogni puntatore non NULL in questa matrice può essere convertito in modo sicuro in un puntatore all'interfaccia sink usando un operatore cast.

CConnectionPoint::GetContainer

Chiamato dal framework per recuperare l'oggetto IConnectionPointContainer per il punto di connessione.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Valore restituito

In caso di esito positivo, un puntatore al contenitore; in caso contrario NULL.

Osservazioni:

Questa funzione viene in genere implementata dalla macro BEGIN_CONNECTION_PART.

CConnectionPoint::GetIID

Chiamato dal framework per recuperare l'ID interfaccia di un punto di connessione.

virtual REFIID GetIID() = 0;

Valore restituito

Riferimento all'ID dell'interfaccia del punto di connessione.

Osservazioni:

Eseguire l'override di questa funzione per restituire l'ID interfaccia per questo punto di connessione.

CConnectionPoint::GetMaxConnections

Chiamato dal framework per recuperare il numero massimo di connessioni supportate dal punto di connessione.

virtual int GetMaxConnections();

Valore restituito

Numero massimo di connessioni supportate dal controllo oppure -1 se non è previsto alcun limite.

Osservazioni:

L'implementazione predefinita restituisce -1, che indica che non è previsto alcun limite.

Eseguire l'override di questa funzione se si desidera limitare il numero di sink che possono connettersi al controllo.

CConnectionPoint::GetNextConnection

Recupera un puntatore all'elemento di connessione in corrispondenza di pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parametri

pos
Specifica un riferimento a un valore POSITION restituito da una chiamata precedente GetNextConnection o GetStartPosition .

Valore restituito

Puntatore all'elemento di connessione specificato da pos o NULL.

Osservazioni:

Questa funzione è più utile per scorrere tutti gli elementi nella mappa di connessione. Durante l'iterazione, ignorare gli eventuali valori NULL restituiti da questa funzione.

Esempio

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

Avvia un'iterazione della mappa restituendo un valore POSITION che può essere passato a una chiamata GetNextConnection .

POSITION GetStartPosition() const;

Valore restituito

Valore POSITION che indica una posizione iniziale per l'iterazione della mappa; o NULL se la mappa è vuota.

Osservazioni:

La sequenza di iterazione non è prevedibile; pertanto, il "primo elemento nella mappa" non ha un significato speciale.

Esempio

Vedere l'esempio per CConnectionPoint::GetNextConnection.

CConnectionPoint::OnAdvise

Chiamato dal framework quando viene stabilita o interrotta una connessione.

virtual void OnAdvise(BOOL bAdvise);

Parametri

bAdvise
TRUE, se viene stabilita una connessione; in caso contrario FALSE.

Osservazioni:

L'implementazione predefinita non esegue alcuna operazione.

Eseguire l'override di questa funzione se si vuole notificare quando i sink si connettono o si disconnettono dal punto di connessione.

CConnectionPoint::QuerySinkInterface

Recupera un puntatore all'interfaccia sink richiesta.

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

Parametri

pUnkSink
Identificatore dell'interfaccia sink richiesta.

ppInterface
Puntatore al puntatore dell'interfaccia identificato da pUnkSink. Se l'oggetto non supporta questa interfaccia, * ppInterface è impostato su NULL.

Valore restituito

Valore HRESULT standard.

Vedi anche

Classe CCmdTarget
Grafico della gerarchia