Класс CConnectionPoint

Определяет особый тип интерфейса, используемый для взаимодействия с другими объектами OLE и называемый "точкой подключения".

Синтаксис

class CConnectionPoint : public CCmdTarget

Участники

Открытые конструкторы

Имя	Описание
CConnectionPoint::CConnectionPoint	Формирует объект CConnectionPoint.

Открытые методы

Имя	Описание
CConnectionPoint::GetConnections	Извлекает все точки подключения в карте подключения.
CConnectionPoint::GetContainer	Извлекает контейнер элемента управления, который владеет картой подключения.
CConnectionPoint::GetIID	Извлекает идентификатор интерфейса точки подключения.
CConnectionPoint::GetMaxConnections	Извлекает максимальное количество точек подключения, поддерживаемых элементом управления.
CConnectionPoint::GetNextConnection	Извлекает указатель на элемент подключения в pos.
CConnectionPoint::GetStartPosition	Запускает итерацию карты, возвращая значение POSITION, которое можно передать вызову GetNextConnection .
CConnectionPoint::OnAdvise	Вызывается платформой при установке или нарушении подключений.
CConnectionPoint::QuerySinkInterface	Извлекает указатель на запрошенный интерфейс приемника.

Замечания

В отличие от обычных интерфейсов OLE, которые используются для реализации и предоставления функциональных возможностей элемента управления OLE, точка подключения реализует исходящий интерфейс, который может инициировать действия на других объектах, таких как срабатывание событий и уведомлений об изменениях.

Соединение состоит из двух частей: объекта, вызывающего интерфейс, который называется "источником", и объект, реализующий интерфейс, называемый приемником. Предоставляя точку подключения, источник позволяет приемникам устанавливать подключения к себе. Через механизм точки подключения исходный объект получает указатель на реализацию приемника набора функций-членов. Например, чтобы вызвать событие, реализованное приемником, источник может вызвать соответствующий метод реализации приемника.

По умолчанию производный COleControlкласс реализует две точки подключения: один для событий и один для уведомлений об изменении свойств. Эти подключения используются соответственно для запуска событий и уведомления приемника (например, контейнера элемента управления) при изменении значения свойства. Поддержка также предоставляется для элементов управления OLE для реализации дополнительных точек подключения. Для каждой дополнительной точки подключения, реализованной в классе управления, необходимо объявить "часть подключения", реализующую точку подключения. Если вы реализуете одну или несколько точек подключения, необходимо также объявить одну карту подключения в классе управления.

В следующем примере показана простая карта подключения и одна точка подключения для Sample элемента управления OLE, состоящая из двух фрагментов кода: первая часть объявляет карту подключения и точку; вторая реализует эту карту и точку. Первый фрагмент вставляется в объявление класса элемента управления в разделе protected :

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

DECLARE_CONNECTION_MAP()

Макросы BEGIN_CONNECTION_PART и END_CONNECTION_PART объявляют внедренный класс XSampleConnPt (производный от CConnectionPoint), который реализует эту конкретную точку подключения. Если вы хотите переопределить любые CConnectionPoint функции-члены или добавить собственные функции-члены, объявите их между этими двумя макросами. Например, макрос CONNECTION_IID переопределяет CConnectionPoint::GetIID функцию-член при размещении между этими двумя макросами.

Второй фрагмент кода вставляется в файл реализации (. CPP) класса элемента управления. Этот код реализует карту подключения, которая включает дополнительную точку подключения, SampleConnPt:

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

После вставки этих фрагментов кода элемент управления OLE образец предоставляет точку подключения для ISampleSink интерфейса.

Как правило, точки подключения поддерживают многоадресную рассылку, которая позволяет транслировать несколько приемников, подключенных к одному интерфейсу. В следующем фрагменте кода показано, как выполнить многоадресную рассылку путем итерации по каждому приемнику в точке подключения:

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

В этом примере извлекается текущий набор подключений в точке SampleConnPt подключения с вызовом CConnectionPoint::GetConnections. Затем он выполняет итерацию по подключениям и вызовам ISampleSink::SinkFunc для каждого активного подключения.

Дополнительные сведения об использовании CConnectionPointсм. в статье "Точки подключения".

Иерархия наследования

CObject

CCmdTarget

CConnectionPoint

Требования

Заголовок: afxdisp.h

CConnectionPoint::CConnectionPoint

Формирует объект CConnectionPoint.

CConnectionPoint();

CConnectionPoint::GetConnections

Вызовите эту функцию, чтобы получить все активные подключения для точки подключения.

const CPtrArray* GetConnections();

Возвращаемое значение

Указатель на массив активных подключений (приемников). Некоторые указатели в массиве могут иметь значение NULL. Каждый указатель, отличный от NULL в этом массиве, можно безопасно преобразовать в указатель на интерфейс приемника с помощью оператора приведения.

CConnectionPoint::GetContainer

Вызывается платформой для получения IConnectionPointContainer точки подключения.

virtual LPCONNECTIONPOINTCONTAINER GetContainer();

Возвращаемое значение

В случае успешного выполнения указатель на контейнер; в противном случае ЗНАЧЕНИЕ NULL.

Замечания

Обычно эта функция реализуется макросом BEGIN_CONNECTION_PART.

CConnectionPoint::GetIID

Вызывается платформой для получения идентификатора интерфейса точки подключения.

virtual REFIID GetIID() = 0;

Возвращаемое значение

Ссылка на идентификатор интерфейса точки подключения.

Замечания

Переопределите эту функцию, чтобы вернуть идентификатор интерфейса для этой точки подключения.

CConnectionPoint::GetMaxConnections

Вызывается платформой для получения максимального количества подключений, поддерживаемых точкой подключения.

virtual int GetMaxConnections();

Возвращаемое значение

Максимальное количество подключений, поддерживаемых элементом управления, или -1, если ограничение не ограничено.

Замечания

Реализация по умолчанию возвращает значение -1, указывающее отсутствие ограничения.

Переопределите эту функцию, если вы хотите ограничить количество приемников, которые могут подключаться к элементу управления.

CConnectionPoint::GetNextConnection

Извлекает указатель на элемент подключения в pos.

LPUNKNOWN GetNextConnection(POSITION& pos) const;

Параметры

pos
Указывает ссылку на значение POSITION, возвращаемое предыдущим GetNextConnection или вызовом GetStartPosition .

Возвращаемое значение

Указатель на элемент подключения, указанный в pos или NULL.

Замечания

Эта функция наиболее полезна для итерации всех элементов карты подключения. При итерации пропустите все NUL-адреса, возвращаемые из этой функции.

Пример

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

Запускает итерацию карты, возвращая значение POSITION, которое можно передать в вызов GetNextConnection .

POSITION GetStartPosition() const;

Возвращаемое значение

Значение POSITION, указывающее начальную позицию для итерации карты; или NULL, если карта пуста.

Замечания

Последовательность итерации не предсказуема; Таким образом, "первый элемент в карте" не имеет особого значения.

Пример

См. пример CConnectionPoint::GetNextConnection.

CConnectionPoint::OnAdvise

Вызывается платформой при установке или разрыве соединения.

virtual void OnAdvise(BOOL bAdvise);

Параметры

bAdvise
ЗНАЧЕНИЕ TRUE, если устанавливается подключение; в противном случае ЗНАЧЕНИЕ FALSE.

Замечания

Реализация по умолчанию не выполняет никаких действий.

Переопределите эту функцию, если требуется уведомление при подключении приемников к точке подключения или отключению от нее.

CConnectionPoint::QuerySinkInterface

Извлекает указатель на запрошенный интерфейс приемника.

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

Параметры

pUnkSink
Идентификатор запрашиваемого интерфейса приемника.

ppInterface
Указатель на указатель интерфейса, определенный pUnkSink. Если объект не поддерживает этот интерфейс, значение * ppInterface имеет значение NULL.

Возвращаемое значение

Стандартное значение HRESULT.

См. также

Класс CCmdTarget
Диаграмма иерархии