CConnectionPoint 类

项目
10/12/2023

定义用于与其他 OLE 对象通信的接口（称为“连接点”）的特殊类型。

语法

class CConnectionPoint : public CCmdTarget

成员

公共构造函数

名称	描述
CConnectionPoint::CConnectionPoint	构造 `CConnectionPoint` 对象。

公共方法

名称	描述
CConnectionPoint::GetConnections	检索连接映射中的所有连接点。
CConnectionPoint::GetContainer	检索拥有连接映射的控件的容器。
CConnectionPoint::GetIID	检索连接点的接口 ID。
CConnectionPoint::GetMaxConnections	检索控件支持的最大连接点数。
CConnectionPoint::GetNextConnection	检索指向位于 pos 的连接元素的指针。
CConnectionPoint::GetStartPosition	通过返回可传递给 `GetNextConnection` 调用的 POSITION 值来启动映射迭代。
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 and 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();
      }
   }
}

此示例通过调用 CConnectionPoint::GetConnections 检索 SampleConnPt 连接点上的当前连接集合。然后，它循环访问连接，并调用每个活动连接上的 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

由框架调用以检索连接点的接口 ID。

virtual REFIID GetIID() = 0;

返回值

对连接点的接口 ID 的引用。

备注

替代此函数以返回此连接点的接口 ID。

CConnectionPoint::GetMaxConnections

由框架调用以检索由连接点支持的最大连接数。

virtual int GetMaxConnections();

返回值

控件支持的最大连接数，如果没有限制，则为 -1。

备注

默认实现返回 -1，表示没有限制。

如果要限制可连接到控件的接收器数，请替代此函数。

CConnectionPoint::GetNextConnection

检索指向位于 pos 的连接元素的指针。

LPUNKNOWN GetNextConnection(POSITION& pos) const;

参数

pos
指定对由上一个 GetNextConnection 或 GetStartPosition 调用返回的 POSITION 值的引用。

返回值

指向由 pos 或 NULL 指定的连接元素的指针。

备注

此函数对于循环访问连接映射中的所有元素最有用。循环访问时，请跳过从此函数返回的任何 NULL。

示例

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

通过返回可传递给 GetNextConnection 调用的 POSITION 值来启动映射迭代。

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 类
 层次结构图

通过