Klasa CConnectionPoint

Definiuje specjalny typ interfejsu używany do komunikowania się z innymi obiektami OLE nazywany "punktem połączenia".

Składnia

class CConnectionPoint : public CCmdTarget

Elementy członkowskie

Konstruktory publiczne

Nazwa/nazwisko	opis
CConnectionPoint::CConnectionPoint	CConnectionPoint Tworzy obiekt.

Metody publiczne

Nazwa/nazwisko	opis
CConnectionPoint::GetConnections	Pobiera wszystkie punkty połączenia na mapie połączeń.
CConnectionPoint::GetContainer	Pobiera kontener kontrolki, która jest właścicielem mapy połączeń.
CConnectionPoint::GetIID	Pobiera identyfikator interfejsu punktu połączenia.
CConnectionPoint::GetMaxConnections	Pobiera maksymalną liczbę punktów połączenia obsługiwanych przez kontrolkę.
CConnectionPoint::GetNextConnection	Pobiera wskaźnik do elementu połączenia w punkcie pos.
CConnectionPoint::GetStartPosition	Uruchamia iterację mapy, zwracając wartość POSITION, którą można przekazać do wywołania GetNextConnection .
CConnectionPoint::OnAdvise	Wywoływana przez platformę podczas nawiązywania lub przerywania połączeń.
CConnectionPoint::QuerySinkInterface	Pobiera wskaźnik do żądanego interfejsu ujścia.

Uwagi

W przeciwieństwie do normalnych interfejsów OLE, które są używane do implementowania i uwidaczniania funkcjonalności kontrolki OLE, punkt połączenia implementuje interfejs wychodzący, który umożliwia inicjowanie akcji na innych obiektach, takich jak wyzwalanie zdarzeń i powiadamianie o zmianie.

Połączenie składa się z dwóch części: obiektu wywołującego interfejs, nazywanego "źródłem" i obiektem implementącym interfejs, nazywanym "ujściem". Uwidaczniając punkt połączenia, źródło umożliwia ujściom nawiązywanie połączeń z samym sobą. Za pośrednictwem mechanizmu punktu połączenia obiekt źródłowy uzyskuje wskaźnik do implementacji ujścia zestawu funkcji składowych. Na przykład w celu wyzwolenia zdarzenia zaimplementowanego przez ujście źródło może wywołać odpowiednią metodę implementacji ujścia.

Domyślnie klasa -pochodna COleControlimplementuje dwa punkty połączenia: jeden dla zdarzeń i jeden dla powiadomień o zmianie właściwości. Te połączenia są używane odpowiednio do wyzwalania zdarzeń i powiadamiania ujścia (na przykład kontenera kontrolki), gdy wartość właściwości uległa zmianie. Dostępna jest również obsługa kontrolek OLE w celu zaimplementowania dodatkowych punktów połączenia. Dla każdego dodatkowego punktu połączenia zaimplementowanego w klasie kontrolnej należy zadeklarować "część połączenia", która implementuje punkt połączenia. W przypadku zaimplementowania co najmniej jednego punktu połączenia należy również zadeklarować pojedynczą "mapę połączenia" w klasie kontrolnej.

W poniższym przykładzie pokazano prostą mapę połączenia i jeden punkt połączenia dla Sample kontrolki OLE składający się z dwóch fragmentów kodu: pierwsza część deklaruje mapę połączenia i punkt; druga implementuje tę mapę i punkt. Pierwszy fragment jest wstawiany do deklaracji klasy kontrolnej protected w sekcji:

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

DECLARE_CONNECTION_MAP()

Makra BEGIN_CONNECTION_PART i END_CONNECTION_PART deklarują klasę XSampleConnPt osadzoną (pochodzącą z CConnectionPointklasy ), która implementuje ten konkretny punkt połączenia. Jeśli chcesz zastąpić dowolne CConnectionPoint funkcje składowe lub dodać własne funkcje członkowskie, zadeklaruj je między tymi dwoma makrami. Na przykład makro CONNECTION_IID zastępuje CConnectionPoint::GetIID funkcję składową podczas umieszczania między tymi dwoma makrami.

Drugi fragment kodu jest wstawiany do pliku implementacji (. CPP) klasy kontrolnej. Ten kod implementuje mapę połączenia, która zawiera dodatkowy punkt połączenia, SampleConnPt:

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

Po wstawieniu tych fragmentów kodu przykładowa kontrolka OLE uwidacznia punkt połączenia dla interfejsu ISampleSink .

Zazwyczaj punkty połączenia obsługują "multiemisję", co jest możliwością emisji do wielu ujściów połączonych z tym samym interfejsem. Poniższy fragment kodu pokazuje, jak wykonać multiemisję przez iterowanie po każdym ujściu w punkcie połączenia:

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

W tym przykładzie jest pobierany bieżący zestaw połączeń w SampleConnPt punkcie połączenia z wywołaniem metody CConnectionPoint::GetConnections. Następnie wykonuje iterację za pośrednictwem połączeń i wywołuje ISampleSink::SinkFunc każde aktywne połączenie.

Aby uzyskać więcej informacji na temat korzystania z programu CConnectionPoint, zobacz artykuł Punkty połączenia.

Hierarchia dziedziczenia

Obiekt CObject

CCmdTarget

CConnectionPoint

Wymagania

Nagłówek: afxdisp.h

CConnectionPoint::CConnectionPoint

CConnectionPoint Tworzy obiekt.

CConnectionPoint();

CConnectionPoint::GetConnections

Wywołaj tę funkcję, aby pobrać wszystkie aktywne połączenia dla punktu połączenia.

const CPtrArray* GetConnections();

Wartość zwracana

Wskaźnik do tablicy aktywnych połączeń (ujścia). Niektóre wskaźniki w tablicy mogą mieć wartość NULL. Każdy wskaźnik inny niż NULL w tej tablicy można bezpiecznie przekonwertować na wskaźnik do interfejsu ujścia przy użyciu operatora rzutowania.

CConnectionPoint::GetContainer

Wywoływana przez platformę w celu pobrania IConnectionPointContainer elementu dla punktu połączenia.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Wartość zwracana

Jeśli operacja powiedzie się, wskaźnik do kontenera; w przeciwnym razie wartość NULL.

Uwagi

Ta funkcja jest zwykle implementowana przez makro BEGIN_CONNECTION_PART.

CConnectionPoint::GetIID

Wywoływana przez platformę w celu pobrania identyfikatora interfejsu punktu połączenia.

virtual REFIID GetIID() = 0;

Wartość zwracana

Odwołanie do identyfikatora interfejsu punktu połączenia.

Uwagi

Zastąpi tę funkcję, aby zwrócić identyfikator interfejsu dla tego punktu połączenia.

CConnectionPoint::GetMaxConnections

Wywoływana przez platformę w celu pobrania maksymalnej liczby połączeń obsługiwanych przez punkt połączenia.

virtual int GetMaxConnections();

Wartość zwracana

Maksymalna liczba połączeń obsługiwanych przez kontrolkę lub -1, jeśli nie ma limitu.

Uwagi

Domyślna implementacja zwraca wartość -1, co oznacza brak limitu.

Zastąpi tę funkcję, jeśli chcesz ograniczyć liczbę ujść, które mogą łączyć się z kontrolką.

CConnectionPoint::GetNextConnection

Pobiera wskaźnik do elementu połączenia w punkcie pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Parametry

pozytyw
Określa odwołanie do wartości POSITION zwróconej przez poprzednie GetNextConnection wywołanie lub GetStartPosition .

Wartość zwracana

Wskaźnik do elementu połączenia określonego przez wiersz polecenia lub wartość NULL.

Uwagi

Ta funkcja jest najbardziej przydatna do iterowania wszystkich elementów na mapie połączeń. Podczas iteracji pomiń wszystkie elementy NUL Zwrócone z tej funkcji.

Przykład

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

Uruchamia iterację mapy, zwracając wartość POSITION, którą można przekazać do wywołania GetNextConnection .

POSITION GetStartPosition() const;

Wartość zwracana

Wartość POZYCJA wskazująca pozycję początkową do iterowania mapy; lub null, jeśli mapa jest pusta.

Uwagi

Sekwencja iteracji nie jest przewidywalna; dlatego "pierwszy element na mapie" nie ma specjalnego znaczenia.

Przykład

Zobacz przykład CConnectionPoint::GetNextConnectionConnection.

CConnectionPoint::OnAdvise

Wywoływana przez platformę w przypadku ustanowienia lub przerwania połączenia.

virtual void OnAdvise(BOOL bAdvise);

Parametry

bAdvise
PRAWDA, jeśli jest ustanawiane połączenie; w przeciwnym razie FAŁSZ.

Uwagi

Domyślna implementacja nic nie robi.

Zastąpi tę funkcję, jeśli chcesz otrzymywać powiadomienia, gdy ujścia łączą się z punktem połączenia lub rozłączają się z tym punktem połączenia.

CConnectionPoint::QuerySinkInterface

Pobiera wskaźnik do żądanego interfejsu ujścia.

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

Parametry

pUnkSink
Identyfikator żądanego interfejsu ujścia.

ppInterface
Wskaźnik do wskaźnika interfejsu zidentyfikowany przez pUnkSink. Jeśli obiekt nie obsługuje tego interfejsu, * ppInterface ma wartość NULL.

Wartość zwracana

Standardowa wartość HRESULT.

Zobacz też

Klasa CCmdTarget
Wykres hierarchii