连接映射

  • 项目

OLE 控件能够向其他应用程序公开接口。 这些接口只允许从容器访问该控件。 如果某个 OLE 控件想要访问其他 OLE 对象的外部接口，则必须建立连接点。 此连接点允许控件对外部调度映射进行传出访问，例如事件映射或通知功能。

Microsoft 基础类库提供了一个支持连接点的编程模型。 在此模型中，“连接映射”用于为 OLE 控件指定接口或连接点。 连接映射包含每个连接点的一个宏。 有关连接映射的详细信息，请参阅 CConnectionPoint 类。

通常，控件仅支持两个连接点：一个用于事件，另一个用于属性通知。 这些连接点都是由 COleControl 基类实现的，不需要控件编写器执行额外的工作。 必须手动添加想要在类中实现的任何其他连接点。 为支持连接映射和点，MFC 提供了以下宏：

连接映射声明和划分

名称 描述
BEGIN_CONNECTION_PART 声明用于实现附加连接点的嵌入类（必须在类声明中使用）。
END_CONNECTION_PART 结束连接点的声明（必须在类声明中使用）。
CONNECTION_IID 指定控件的连接点的接口 ID。
DECLARE_CONNECTION_MAP 声明将在类中使用连接映射（必须在类声明中使用）。
BEGIN_CONNECTION_MAP 开始连接映射的定义（必须在类实现中使用）。
END_CONNECTION_MAP 结束连接映射的定义（必须在类实现中使用）。
CONNECTION_PART 在控件的连接映射中指定连接点。

以下函数帮助接收器使用连接点建立和断开连接：

连接点的开始/终止

名称 描述
AfxConnectionAdvise 在源和接收器之间建立连接。
AfxConnectionUnadvise 断开源和接收器之间的连接。

BEGIN_CONNECTION_PART

使用 BEGIN_CONNECTION_PART 宏开始定义事件和属性通知连接点之外的其他连接点。

BEGIN_CONNECTION_PART(theClass, localClass)

参数

theClass 指定连接点所属的控件类的名称。

localClass 指定实现连接点的局部类的名称。

注解

在定义类的成员函数的声明 (.h) 文件中，使用 BEGIN_CONNECTION_PART 宏启动连接点。 然后添加要实现的 CONNECTION_IID 宏和其他成员函数。 最后，使用 END_CONNECTION_PART 宏完成连接映射。

要求

页眉afxdisp.h

END_CONNECTION_PART

结束连接点的声明。

END_CONNECTION_PART(localClass)

参数

localClass
指定实现连接点的局部类的名称。

要求

页眉afxdisp.h

CONNECTION_IID

在 BEGIN_CONNECTION_PART 和 END_CONNECTION_PART 宏之间使用，以定义 OLE 控件支持的连接点的接口 ID。

CONNECTION_IID(iid)

参数

iid
接口的接口 ID 由连接点调用。

注解

iid 参数是一个接口 ID，用于标识连接点在其连接的接收器中调用的接口。 例如：

CONNECTION_IID(IID_ISampleSink)

指定调用 ISinkInterface 接口的连接点。

要求

页眉afxdisp.h

DECLARE_CONNECTION_MAP

程序中的每个 COleControl 派生类可提供一个连接映射来指定控件支持的额外的连接点。

DECLARE_CONNECTION_MAP()

备注

如果控件支持额外的点，请在类声明的末尾使用 DECLARE_CONNECTION_MAP 宏。 然后，在定义类的成员函数的 .cpp 文件中，使用 BEGIN_CONNECTION_MAP 宏，对控件的每个连接点使用 CONNECTION_PART 宏，使用 END_CONNECTION_MAP 宏声明连接映射的结尾。

要求

页眉afxdisp.h

BEGIN_CONNECTION_MAP

程序中的每个 COleControl 派生类均可提供连接映射来指定控件将支持的连接点。

BEGIN_CONNECTION_MAP(theClass, theBase)

参数

theClass
指定连接映射所属的控件类的名称。

theBase
指定 theClass 的基类的名称。

备注

在定义类的成员函数的实现 (.CPP) 文件中，使用 BEGIN_CONNECTION_MAP 宏启动连接映射，然后使用 CONNECTION_PART 宏为每个连接点添加宏条目。 最后，使用 END_CONNECTION_MAP 宏完成连接映射。

要求

页眉afxdisp.h

END_CONNECTION_MAP

结束连接映射的定义。

END_CONNECTION_MAP()

要求

页眉afxdisp.h

CONNECTION_PART

将 OLE 控件的连接点映射到特定的接口 ID。

CONNECTION_PART(theClass, iid, localClass)

参数

theClass
指定连接点所属的控件类的名称。

iid
接口的接口 ID 由连接点调用。

localClass
指定实现连接点的局部类的名称。

备注

例如：

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

使用调用 IID_ISinkInterface 接口的连接点实现连接映射。

要求

页眉afxdisp.h

AfxConnectionAdvise

调用此函数以在由 pUnkSrc 指定的源和由 pUnkSink 指定的接收器之间建立连接。

BOOL AFXAPI AfxConnectionAdvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD FAR* pdwCookie);

参数

pUnkSrc
指向调用接口的对象的指针。

pUnkSink
指向实现接口的对象的指针。

iid
连接的接口 ID。

bRefCount
对于进程外连接，此参数必须是 TRUE，并指示创建连接会导致引用计数 pUnkSink 递增。

对于进程内连接，TRUE 指示创建连接会导致 pUnkSink 的引用计数递增。 FALSE 指示引用计数不应递增。

警告：一般情况下，无法预测哪些连接在进程内，哪些连接在进程外，因此建议始终将此参数设置为 TRUE。

pdwCookie
指向返回连接标识符的 DWORD 的指针。 断开连接时，应将此值作为 dwCookie 参数传递给 AfxConnectionUnadvise。

返回值

如果建立了连接，则为非零值；否则为 0。

示例

//CMySink is a CCmdTarget-derived class supporting automation.
//Instantiate the sink class.
CMySink mysink;

//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Establish a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a cookie identifying the connection, and is needed
//to terminate this connection.
AfxConnectionAdvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, &dwCookie);

要求

标头afxctl.h：

AfxConnectionUnadvise

调用此函数以在由 pUnkSrc 指定的源和由 pUnkSink 指定的接收器之间断开连接。

BOOL AFXAPI AfxConnectionUnadvise(
    LPUNKNOWN pUnkSrc,
    REFIID iid,
    LPUNKNOWN pUnkSink,
    BOOL bRefCount,
    DWORD dwCookie);

参数

pUnkSrc
指向调用接口的对象的指针。

pUnkSink
指向实现接口的对象的指针。

iid
连接点接口的接口 ID。

bRefCount
对于进程外连接，此参数必须为 TRUE，并指示创建连接会导致引用计数 pUnkSink 递减。

对于进程内连接，TRUE 指示创建连接会导致引用计数 pUnkSink 递减。 FALSE 指示引用计数不应递减。

警告：一般情况下，无法预测哪些连接在进程内，哪些连接在进程外，因此建议始终将此参数设置为 TRUE。

dwCookie
由 AfxConnectionAdvise 返回的连接标识符。

返回值

如果断开了连接，则为非零值；否则为 0。

示例

//mysink is a CCmdTarget-derived class supporting automation.
//Get a pointer to sink's IUnknown, no AddRef done.
IID iid = IID_IUnknown;
IUnknown* pUnkSink = mysink.GetInterface(&iid);

//Terminate a connection between source and sink.
//pUnkSrc is IUnknown of server obtained by CoCreateInstance().
//dwCookie is a value obtained through AfxConnectionAdvise().
AfxConnectionUnadvise(pUnkSrc, IID_ISampleSink, pUnkSink, FALSE, dwCookie);

要求

标头afxctl.h：

另请参阅

宏和全局函数