{"id":4113,"date":"2013-06-11T07:00:00","date_gmt":"2013-06-11T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2013\/06\/11\/an-introduction-to-com-connection-points\/"},"modified":"2013-06-11T07:00:00","modified_gmt":"2013-06-11T07:00:00","slug":"an-introduction-to-com-connection-points","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20130611-00\/?p=4113","title":{"rendered":"An introduction to COM connection points"},"content":{"rendered":"

\n\nLast time<\/A>,\nwe saw how to enumerate all the Internet Explorer and\nExplorer Windows and see what they are viewing.\nBut that program printed static information.\nIt didn’t track the changes to the windows if the user\nclicked to another Web page or navigated to a different folder.\n<\/P>\n

\nIn order to hook that up, we\nneed to understand the connection point model and the\nway events are expressed in dispatch interfaces.\nFirst, let’s look at the connection point model.\nThese topics confused me when I first met them\n(in part because I didn’t do a good job of mentally\nseparating them into two topics and instead treated it\nas one big topic),\nso I’m going to spend a few days\ntrying to explain how it works,\nand then later this week, we’ll actually hook things up.\n(And actually hooking it up is a lot easier than explaining it.)\n<\/P>\n

\nToday, the connection point model.\n<\/P>\n

\nSuppose you have a widget which can have multiple clients.\nThe clients can communicate with the widget by invoking methods\non the widget, like\nIWidget::Set­Color<\/CODE>.\nbut how does the widget communicate with its clients?\nWell, since this is COM, the first thing you need is an interface,\nsay,\nIWidget­Client<\/CODE>.\nThe idea is that each client implements\nIWidget­Client<\/CODE>,\nand when the widget needs to, say, notify each client that\nthe color changed,\nit can invoke\nIWidget­Client::On­Color­Changed<\/CODE>\non each one.\nEach client can register with the widget for notifications.\n<\/P>\n

\nThe COM interface for standardizing the registration mechanism\nis IConnection­Point<\/CODE>.\nA connection point<\/I>\nacts as a middle-man between\nthe widget and all its clients:\nWhenever the widget needs to notify all its clients,\nit tells the connection point to do it.\n<\/P>\n\n\n
\n\n \n \n \n \n
\n Widget<\/TD>\n <\/TD>\n \n Connection
Point<\/TD>\n 		→<\/TD>\n \n Client A<\/TD>\n<\/TR>\n
<\/TD>\n <\/TD>\n <\/TD>\n<\/TR>\n
→<\/TD>\n →<\/TD>\n \n Client B<\/TD>\n<\/TR>\n
<\/TD>\n <\/TD>\n <\/TD>\n<\/TR>\n
<\/TD>\n →<\/TD>\n \n Client C<\/TD>\n<\/TR>\n<\/TABLE>\n

\nA client registers with a connection point by calling\nIConnection­Point::Advise<\/CODE>,\nand it unregisters by calling\nIConnection­Point::Unadvise<\/CODE>.\n<\/P>\n

\nOkay, that’s great,\nbut how do clients find the connection point so they can register with it?\n<\/P>\n

\nThe widget exposes an interface known as\nIConnection­Point­Container<\/CODE>\nwhich provides access to an object’s connection points.\nThe client can call the\nIConnection­Point­Container::Find­Connection­Point<\/CODE> method\nto get access to a specific connection point.\n<\/P>\n

\nHere’s how the pieces fit together:\n<\/P>\n

\n\/\/ error checking elided for expository purposes<\/p>\n
void IUnknown_FindConnectionPoint(IUnknown *punk,\n                                  REFIID riid,\n                                  IConnectionPoint **ppcp)\n{\n \/\/ get the IConnectionPointContainer interface\n CComQIPtr<IConnectionPointContainer> spcpc(punk);<\/p>\n
 \/\/ Locate the connection point\n spcpc->FindConnectionPoint(riid,  ppcp);\n}<\/p>\n
class CClient : public IWidgetClient\n{\n…\n IWidget *m_pWidget;\n DWORD m_dwCookie;\n};<\/p>\n
CClient::RegisterWidgetClient()\n{\n \/\/ Find the IWidgetClient connection point\n CComPtr<IConnectionPoint> spcp;\n IUnknown_FindConnectionPoint(m_pWidget,\n                              IID_IWidgetClient, &spcp);<\/p>\n
 \/\/ register with it\n spcp->Advise(this, &m_dwCookie);\n}<\/p>\n
CClient::UnregisterWidgetClient()\n{\n \/\/ Find the IWidgetClient connection point\n CComPtr<IConnectionPoint> spcp;\n IUnknown_FindConnectionPoint(m_pWidget,\n                              IID_IWidgetClient, &spcp);<\/p>\n
 \/\/ unregister from it\n spcp->Unadvise(m_dwCookie);\n}\n<\/PRE>\n
\nAfter registering as a widget client,\nthe CClient<\/CODE> object will receive\nmethod calls on its IWidget­Client<\/CODE>\nuntil it unregisters.\n<\/P>\n
\nNow the widget and clients have two-way communication.\nIf the clients want to initiate the communuication,\nit can call a method on IWidget<\/CODE>.\nIf the widget wants to initiate the communication,\nit can call a method on IWidget­Client<\/CODE>.\n<\/P>\n
\nNote that we’ve created a giant circular reference.\nThe widget has a reference to its connection point\n(so it can tell it to fire a notification to all its clients),\nand the connection point has a reference to the widget\nclient\n(so it can forward the notification along),\nand the widget client has a reference to the widget\nin its m_pWidget<\/CODE> member.\nIn order to break this cycle,\nyou have to remember to explicitly call\nUnregister­Widget­Client<\/CODE>\nwhen you are no longer interested in receiving\nwidget notifications.\n<\/P>\n
\nNote that even though the arrows in the diagram above\nflow from left to right (from widget to clients),\nthat doesn’t mean that the\ninformation flow is strictly left-to-right.\nYou can pass information in the other direction\nvia return values or output parameters.\n<\/P>\n
\nFor example, there might be a method on\nthe IWidget­Client<\/CODE> interface\ncalled Get­Color<\/CODE>:\n<\/P>\n
\ninterface IWidgetClient : IUnknown\n{\n …\n HRESULT GetColor([out] COLORREF *pclr);\n …\n};\n<\/PRE>\n
\nSince there can be multiple clients, the widget\nneeds to have some sort of rule for deciding which\nclient gets to choose the color.\nIt might decide to ask each client in turn for a color,\nuntil one of them returns S_OK<\/CODE>,\nand that client’s color is used and no further clients\nare notified.\n<\/P>\n
\nOr maybe there’s a method called\nOn­Save<\/CODE>:\n<\/P>\n
\ninterface IWidgetClient : IUnknown\n{\n …\n HRESULT OnSave([in] IPropertyStorage *pps);\n …\n};\n<\/PRE>\n
\nThe convention here might be that all clients\nwill be notified of the Save operation and they\ncan write any additional information to the\nIProperty­Storage<\/CODE> while handing\nthe notification.\n<\/P>\n
\nThose are just examples.\nFeel free to make up your own.\nThe point is that just because the arrows go from the\nwidget to the clients doesn’t mean that information\ncan’t flow back the other way.\n<\/P>\n
\nMost of the time, you have the simple case where\na widget will expose a single connection point.\nIn that case, the generality of the\nIConnection­Point­Container<\/CODE>\nmay seem unnecessary.\nBut it allows you to add new connection points later.\nFor example, you might have multiple client interfaces\nfor different types of clients.\nYou could have\nIWidget­Color­Client<\/CODE>\nfor clients that are interested only in color changes,\nand\nIWidget­Network­Client<\/CODE>\nfor clients that are interested only in monitoring the\nwidget’s network activity.\n<\/P>\n
\nOr maybe you didn’t plan on having multiple connection points\noriginally,\nbut in the second version of your product,\nyou want to add additional methods to\nIWidget­Client<\/CODE>,\nso you need to create\nIWidget­Client2<\/CODE>,\nwhich means that you also need a new connection point for it.\n<\/P>\n
\nNext time, a look at the special case where\nthe client interface is a dispatch interface.\n<\/P><\/p>\n","protected":false},"excerpt":{"rendered":"
Last time, we saw how to enumerate all the Internet Explorer and Explorer Windows and see what they are viewing. But that program printed static information. It didn’t track the changes to the windows if the user clicked to another Web page or navigated to a different folder. In order to hook that up, we […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-4113","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Last time, we saw how to enumerate all the Internet Explorer and Explorer Windows and see what they are viewing. But that program printed static information. It didn’t track the changes to the windows if the user clicked to another Web page or navigated to a different folder. In order to hook that up, we […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4113","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=4113"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4113\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=4113"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=4113"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=4113"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}