C++ COM编程-IConnectionPoint和IConnectionPointContainer接口介绍

0. 基本介绍
头文件：ocidl.h
IConnectionPointContainer和IConnectionPoint接口都继承自IUnknown接口。

可连接对象支持以下功能：

传出接口，如事件集
枚举传出接口的IID的能力
连接和断开接收器与这些传出IID的对象的连接的能力
枚举存在于特定传出接口的连接的能力
1. IConnectionPointContainer类
接口函数
① IConnectionPointContainer::EnumConnectionPoints
函数作用：
创建枚举器对象以遍历可连接对象中支持的所有连接点，每个传出IID一个连接点。

函数原型

HRESULT EnumConnectionPoints(
  IEnumConnectionPoints **ppEnum
);

函数参数
ppEnum：
指向IEnumConnectionPoints接口指针变量的指针，该变量接收指向新创建的枚举器的指针。

函数返回值
S_OK：枚举器对象已成功创建。
E_POINTER：ppEnum中的地址无效。例如，它可能为空。

注意
调用方负责在不再需要枚举器时调用Release。

② IConnectionPointContainer::FindConnectionPoint method
函数作用
如果指定的IID描述了一个支持的传出接口，则返回指向该IID的连接点的IConnectionPoint接口的指针。

函数原型

HRESULT FindConnectionPoint(
  REFIID           riid,
  IConnectionPoint **ppCP
);

函数参数
riid：正在请求其连接点对象的传出接口的接口标识符。
ppCP：IConnectionPoint接口指针变量的地址，该变量接收指向支持riid接口的连接点的指针。如果发生错误，则实现将该值设置为空。

函数返回值
S_OK：完成
E_POINTER：ppCP中的地址无效。例如，它可能为空。
CONNECT_E_NOCONNECTION：此可连接对象不支持riid指定的传出接口。

注意
此方法是与对象的传出接口等效的QueryInterface，其中传出接口使用riid指定，返回的接口指针始终是连接点的指针。

2. IConnectionPoint类
IConnectionPoint接口充当组件所支持的引出接口的一个连接点。客户机程序正是使用该接口与引出接口进行连接的。
组件所支持的每一个引出接口必须提供一个连接点(即实现了IConnectionPoint的一个对象)。通过它客户机可以传送他的接口实现。
组件只在它的QueryInterface实现中向外公开一个IConnectionPointContainer接口，并且每个客户机程序必须通过IConnectionPointContainer来获得一个引出接口的IConnectionPoint实现。

接口函数
① IConnectionPoint::Advise
函数作用
在连接点对象和客户端接收器之间建立连接。
函数原型

HRESULT Advise(
  IUnknown *pUnkSink,
  DWORD    *pdwCookie
);

函数参数
pUnkSink：指向客户端通知接收器上的IUnknown接口的指针。客户端的接收器接收来自连接点的传出呼叫。
pdwCookie：指向唯一标识此连接的返回令牌的指针。调用方稍后使用此令牌将连接传递给IConnectionPoint：：Unadvise方法来删除连接。如果连接未成功建立，则此值为零。
函数返回值
S_OK：连接已建立，*pdwCookie具有连接令牌。
E_POINTER：pUnkSink或pdwCookie中的值无效。例如，任一指针都可以为空。
CONNECT_E_ADVISELIMIT：连接点已达到其连接限制，无法再接受任何连接。
CONNECT_E_CANNOTCONNECT：接收器不支持此连接点所需的接口。
注意
Advise()在连接点和用pUnkSink标识的调用方接收器之间建立连接。
连接点必须调用QueryInterface以获取事件发生时要调用的正确传出接口指针，由连接点管理的传出接口的IID。当IID传递给IConnectionPointContainer::FindConnectionPoint方法时，将返回指向此相同连接点的接口指针。

连接点必须查询pUnkSink指针以获得正确的传出接口。如果此查询失败，则此方法必须返回CONNECT_E_CANNOTCONNECT。
对于连接点的任何给定实例的每个连接，pdwCookie值必须是唯一的。
② IConnectionPoint::EnumConnections method
函数作用
创建一个枚举器对象以迭代此连接点的当前连接。
函数原型

HRESULT EnumConnections(
  IEnumConnections **ppEnum
);

函数参数
ppEnum：指向IEnumConnections接口指针的指针，该接口接收新创建的枚举数。
函数返回值
S_OK：枚举器对象已成功创建。
E_POINTER：ppEnum中的地址无效。例如，它可以为NULL。
E_NOTIMPL：连接点不支持枚举。
注意
调用方负责在不再需要枚举器时调用Release。

③ IConnectionPoint::GetConnectionInterface method
函数作用
检索此连接点管理的传出接口的IID。
函数原型

HRESULT GetConnectionInterface(
  IID *pIID
);

函数参数
pIID：指向此连接点管理的传出接口的标识符的指针。
函数返回值
S_OK：调用者的变量pIID包含此连接点管理的传出接口的标识符。
E_POINTER：pIID中的地址无效。例如，它可能为空。
Remarks
使用IEnumConnectionPoints接口，客户端可以获取指向IConnectionPoint接口的指针。使用该指针和GetConnectionInterface方法，客户端可以确定枚举的每个连接点的IID。从该方法返回的IID必须使调用方能够通过IConnectionPointContainer：：FindConnectionPoint访问同一连接点。
注意
此方法必须在任何连接点中实现；E_NOTIMPL不是可接受的返回值。

④ IConnectionPoint::GetConnectionPointContainer method
函数作用
检索父可连接对象的IConnectionPointContainer接口指针。
函数原型

HRESULT GetConnectionPointContainer(
  IConnectionPointContainer **ppCPC
);

函数参数
ppCPC：指向IConnectionPointContainer接口指针的指针。
函数返回值
表 1
Return code Description
S_OK：已成功返回IConnectionPointContainer指针。
E_POINTER：ppCPC中的值不是有效的接口指针。例如，它可能为空。
注意
此方法调用AddRef。调用方负责调用Release以在完成时释放此指针。

此方法必须在返回之前调用AddRef。
此方法必须在任何连接点中实现；E_NOTIMPL不是可接受的返回值。

⑤ IConnectionPoint::Unadvise method
函数作用
终止先前在连接点对象和客户端接收器之间建立的通知连接。
函数原型

HRESULT Unadvise(
  DWORD dwCookie
);

函数参数
dwCookie：先前从IConnectionPoint：：Advise返回的连接令牌。
函数返回值
S_OK：连接成功终止。
E_POINTER：dwCookie中的值不代表有效的连接。