CConnectionPoint-Klasse

Definiert einen besonderen Schnittstellentyp, "Verbindungspunkt" genannt, der verwendet wird, um mit anderen OLE-Objekten zu kommunizieren.

Syntax

class CConnectionPoint : public CCmdTarget

Member

Öffentliche Konstruktoren

Name	Beschreibung
CConnectionPoint::CConnectionPoint	Erstellt ein CConnectionPoint-Objekt.

Öffentliche Methoden

Name	Beschreibung
CConnectionPoint::GetConnections	Ruft alle Verbindungspunkte in einer Verbindungszuordnung ab.
CConnectionPoint::GetContainer	Ruft den Container des Steuerelements ab, das die Verbindungszuordnung besitzt.
CConnectionPoint::GetIID	Ruft die Schnittstellen-ID eines Verbindungspunkts ab.
CConnectionPoint::GetMaxConnections	Ruft die maximale Anzahl von Verbindungspunkten ab, die von einem Steuerelement unterstützt werden.
CConnectionPoint::GetNextConnection	Ruft einen Zeiger auf das Verbindungselement an pos.
CConnectionPoint::GetStartPosition	Startet eine Karteniteration, indem ein POSITION-Wert zurückgegeben wird, der an einen GetNextConnection Aufruf übergeben werden kann.
CConnectionPoint::OnAdvise	Wird vom Framework beim Einrichten oder Unterbrechen von Verbindungen aufgerufen.
CConnectionPoint::QuerySinkInterface	Ruft einen Zeiger auf die angeforderte Senkenschnittstelle ab.

Hinweise

Im Gegensatz zu normalen OLE-Schnittstellen, die zum Implementieren und Verfügbarmachen der Funktionalität eines OLE-Steuerelements verwendet werden, implementiert ein Verbindungspunkt eine ausgehende Schnittstelle, die Aktionen für andere Objekte initiieren kann, z. B. Auslösen von Ereignissen und Änderungsbenachrichtigungen.

Eine Verbindung besteht aus zwei Teilen: dem Objekt, das die Schnittstelle aufruft, die als "Quelle" bezeichnet wird, und das Objekt, das die Schnittstelle implementiert, die als "Sink" bezeichnet wird. Durch die Exposierung eines Verbindungspunkts ermöglicht eine Quelle senken das Herstellen von Verbindungen zu sich selbst. Über den Verbindungspunktmechanismus ruft ein Quellobjekt einen Zeiger auf die Implementierung einer Gruppe von Memberfunktionen ab. Zum Auslösen eines ereignisses, das von der Spüle implementiert wird, kann die Quelle z. B. die entsprechende Methode der Implementierung der Sink aufrufen.

Standardmäßig implementiert eine COleControlabgeleitete Klasse zwei Verbindungspunkte: eines für Ereignisse und eine für Eigenschaftsänderungsbenachrichtigungen. Diese Verbindungen werden zum Auslösen von Ereignissen bzw. zum Benachrichtigen einer Spüle (z. B. des Steuerelementcontainers) verwendet, wenn sich ein Eigenschaftswert geändert hat. Unterstützung wird auch für OLE-Steuerelemente bereitgestellt, um zusätzliche Verbindungspunkte zu implementieren. Für jeden zusätzlichen Verbindungspunkt, der in Ihrer Steuerelementklasse implementiert ist, müssen Sie einen "Verbindungsteil" deklarieren, der den Verbindungspunkt implementiert. Wenn Sie einen oder mehrere Verbindungspunkte implementieren, müssen Sie auch eine einzelne "Verbindungszuordnung" in Ihrer Steuerelementklasse deklarieren.

Das folgende Beispiel zeigt eine einfache Verbindungszuordnung und einen Verbindungspunkt für das Sample OLE-Steuerelement, bestehend aus zwei Codefragmenten: Der erste Teil deklariert die Verbindungszuordnung und den Punkt; die zweite implementiert diese Karte und diesen Punkt. Das erste Fragment wird in die Deklaration der Steuerelementklasse unter dem protected Abschnitt eingefügt:

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

DECLARE_CONNECTION_MAP()

Die BEGIN_CONNECTION_PART- und END_CONNECTION_PART-Makros deklarieren eine eingebettete Klasse ( XSampleConnPt abgeleitet von CConnectionPoint), die diesen bestimmten Verbindungspunkt implementiert. Wenn Sie Memberfunktionen CConnectionPoint außer Kraft setzen oder Memberfunktionen selbst hinzufügen möchten, deklarieren Sie sie zwischen diesen beiden Makros. Beispielsweise überschreibt das CONNECTION_IID Makro die CConnectionPoint::GetIID Memberfunktion, wenn sie zwischen diesen beiden Makros platziert wird.

Das zweite Codefragment wird in die Implementierungsdatei (. CPP) Ihrer Steuerelementklasse. Dieser Code implementiert die Verbindungszuordnung, die den zusätzlichen Verbindungspunkt enthält: SampleConnPt

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

Nachdem diese Codefragmente eingefügt wurden, macht das Beispiel-OLE-Steuerelement einen Verbindungspunkt für die ISampleSink Schnittstelle verfügbar.

In der Regel unterstützen Verbindungspunkte "Multicasting". Dies ist die Möglichkeit, an mehrere Senken zu übertragen, die mit derselben Schnittstelle verbunden sind. Das folgende Codefragment veranschaulicht, wie Multicasting erreicht wird, indem die einzelnen Senken auf einem Verbindungspunkt durchlaufen werden:

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 diesem Beispiel wird der aktuelle Satz von Verbindungen für den SampleConnPt Verbindungspunkt mit einem Aufruf abgerufen CConnectionPoint::GetConnections. Anschließend durchläuft er die Verbindungen und Aufrufe ISampleSink::SinkFunc für jede aktive Verbindung.

Weitere Informationen zur Verwendung CConnectionPointfinden Sie im Artikel "Connection Points".

Vererbungshierarchie

CObject

CCmdTarget

CConnectionPoint

Anforderungen

Header: afxdisp.h

CConnectionPoint::CConnectionPoint

Erstellt ein CConnectionPoint-Objekt.

CConnectionPoint();

CConnectionPoint::GetConnections

Rufen Sie diese Funktion auf, um alle aktiven Verbindungen für einen Verbindungspunkt abzurufen.

const CPtrArray* GetConnections();

Rückgabewert

Ein Zeiger auf ein Array aktiver Verbindungen (Senken). Einige der Zeiger im Array können NULL sein. Jeder Nicht-NULL-Zeiger in diesem Array kann mithilfe eines Umwandlungsoperators sicher in einen Zeiger auf die Senkenschnittstelle konvertiert werden.

CConnectionPoint::GetContainer

Vom Framework aufgerufen, um den IConnectionPointContainer Verbindungspunkt abzurufen.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Rückgabewert

Bei erfolgreicher Ausführung ein Zeiger auf den Container; andernfalls NULL.

Hinweise

Diese Funktion wird in der Regel vom BEGIN_CONNECTION_PART Makro implementiert.

CConnectionPoint::GetIID

Vom Framework aufgerufen, um die Schnittstellen-ID eines Verbindungspunkts abzurufen.

virtual REFIID GetIID() = 0;

Rückgabewert

Ein Verweis auf die Schnittstellen-ID des Verbindungspunkts.

Hinweise

Überschreiben Sie diese Funktion, um die Schnittstellen-ID für diesen Verbindungspunkt zurückzugeben.

CConnectionPoint::GetMaxConnections

Vom Framework aufgerufen, um die maximale Anzahl von Verbindungen abzurufen, die vom Verbindungspunkt unterstützt werden.

virtual int GetMaxConnections();

Rückgabewert

Die maximale Anzahl von Verbindungen, die vom Steuerelement unterstützt werden, oder -1, wenn kein Grenzwert.

Hinweise

Die Standardimplementierung gibt -1 zurück, die keine Beschränkung angibt.

Überschreiben Sie diese Funktion, wenn Sie die Anzahl der Senken einschränken möchten, die eine Verbindung mit Ihrem Steuerelement herstellen können.

CConnectionPoint::GetNextConnection

Ruft einen Zeiger auf das Verbindungselement an pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parameter

pos
Gibt einen Verweis auf einen POSITION-Wert an, der von einem vorherigen GetNextConnection oder GetStartPosition-Aufruf zurückgegeben wird.

Rückgabewert

Ein Zeiger auf das durch Pos oder NULL angegebene Verbindungselement.

Hinweise

Diese Funktion ist am nützlichsten für das Durchlaufen aller Elemente in der Verbindungszuordnung. Überspringen Sie beim Durchlaufen alle von dieser Funktion zurückgegebenen NULLs.

Beispiel

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

Startet eine Karteniteration, indem ein POSITION-Wert zurückgegeben wird, der an einen GetNextConnection-Aufruf übergeben werden kann.

POSITION GetStartPosition() const;

Rückgabewert

Ein POSITION-Wert, der eine Startposition zum Durchlaufen der Karte angibt; oder NULL, wenn die Zuordnung leer ist.

Hinweise

Die Iterationssequenz ist nicht vorhersehbar; Daher hat das "erste Element in der Karte" keine besondere Bedeutung.

Beispiel

Sehen Sie sich das Beispiel für CConnectionPoint::GetNextConnection an.

CConnectionPoint::OnAdvise

Wird vom Framework aufgerufen, wenn eine Verbindung hergestellt oder unterbrochen wird.

virtual void OnAdvise(BOOL bAdvise);

Parameter

bAdvise
TRUE, wenn eine Verbindung hergestellt wird; andernfalls FALSE.

Hinweise

Bei der Standardimplementierung wird keine Aktion ausgeführt.

Überschreiben Sie diese Funktion, wenn Sie eine Benachrichtigung wünschen, wenn sie eine Verbindung mit Ihrem Verbindungspunkt herstellen oder trennen möchten.

CConnectionPoint::QuerySinkInterface

Ruft einen Zeiger auf die angeforderte Senkenschnittstelle ab.

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

Parameter

pUnkSink
Der Bezeichner der angeforderten Sinkschnittstelle.

ppInterface
Ein Zeiger auf den Schnittstellenzeiger, der von pUnkSink identifiziert wird. Wenn das Objekt diese Schnittstelle nicht unterstützt, wird * ppInterface auf NULL festgelegt.

Rückgabewert

Ein HRESULT-Standardwert.

Siehe auch

CCmdTarget-Klasse
Hierarchiediagramm