Connection Point Global Functions

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Connection Point Global Functions.

These functions provide support for connection points and sink maps.

Important

The functions listed in the following table cannot be used in applications that execute in the Windows Runtime.

AtlAdvise	Creates a connection between an object's connection point and a client's sink.
AtlUnadvise	Terminates the connection established through AtlAdvise.
AtlAdviseSinkMap	Advises or unadvises entries in an event sink map.

AtlAdvise

Creates a connection between an object's connection point and a client's sink.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlAdvise(
    IUnknown* pUnkCP,
    IUnknown* pUnk,
    const IID& iid,
    LPDWORD pdw);

Parameters

pUnkCP
[in] A pointer to the IUnknown of the object the client wants to connect with.

pUnk
[in] A pointer to the client's IUnknown.

iid
[in] The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point.

pdw
[out] A pointer to the cookie that uniquely identifies the connection.

Return Value

A standard HRESULT value.

Remarks

The sink implements the outgoing interface supported by the connection point. The client uses the pdw cookie to remove the connection by passing it to AtlUnadvise.

Example

   LPUNKNOWN m_pSourceUnk;
   LPUNKNOWN m_pSinkUnk;
   DWORD m_dwCustCookie;

   // create source object
   HRESULT hr = CoCreateInstance (CLSID_MyComponent, NULL, CLSCTX_ALL, 
      IID_IUnknown, (LPVOID*)&m_pSourceUnk);
   ATLASSERT(SUCCEEDED(hr));

   // Create sink object.  CMySink is a CComObjectRootEx-derived class 
   // that implements the event interface methods.
   CComObject<CMySink>* pSinkClass;
   CComObject<CMySink>::CreateInstance(&pSinkClass);
   hr = pSinkClass->QueryInterface (IID_IUnknown, (LPVOID*)&m_pSinkUnk);
   ATLASSERT(SUCCEEDED(hr));

   hr = AtlAdvise (m_pSourceUnk, m_pSinkUnk, __uuidof(_IMyComponentEvents), &m_dwCustCookie);
   ATLASSERT(SUCCEEDED(hr));    

AtlUnadvise

Terminates the connection established through AtlAdvise.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlUnadvise(
    IUnknown* pUnkCP,
    const IID& iid,
    DWORD dw);

Parameters

pUnkCP
[in] A pointer to the IUnknown of the object that the client is connected with.

iid
[in] The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point.

dw
[in] The cookie that uniquely identifies the connection.

Return Value

A standard HRESULT value.

Example

   LPUNKNOWN m_pSourceUnk;
   LPUNKNOWN m_pSinkUnk;
   DWORD m_dwCustCookie;

   // create source object
   HRESULT hr = CoCreateInstance (CLSID_MyComponent, NULL, CLSCTX_ALL, 
      IID_IUnknown, (LPVOID*)&m_pSourceUnk);
   ATLASSERT(SUCCEEDED(hr));

   // Create sink object.  CMySink is a CComObjectRootEx-derived class 
   // that implements the event interface methods.
   CComObject<CMySink>* pSinkClass;
   CComObject<CMySink>::CreateInstance(&pSinkClass);
   hr = pSinkClass->QueryInterface (IID_IUnknown, (LPVOID*)&m_pSinkUnk);
   ATLASSERT(SUCCEEDED(hr));

   hr = AtlAdvise (m_pSourceUnk, m_pSinkUnk, __uuidof(_IMyComponentEvents), &m_dwCustCookie);
   ATLASSERT(SUCCEEDED(hr));    

   // do something
   CComBSTR bstrMsg(L"Hi there!");
   ((CMyComponent*)m_pSourceUnk)->Fire_ShowMyMsg(bstrMsg);

   hr = AtlUnadvise (m_pSourceUnk, __uuidof(_IMyComponentEvents), m_dwCustCookie);
   ATLASSERT(SUCCEEDED(hr));

AtlAdviseSinkMap

Call this function to advise or unadvise all entries in the object's sink event map.

Important

This function cannot be used in applications that execute in the Windows Runtime.

HRESULT AtlAdviseSinkMap(T* pT, bool bAdvise);

Parameters

pT
[in] A pointer to the object containing the sink map.

bAdvise
[in] true if all sink entries are to be advised; false if all sink entries are to be unadvised.

Return Value

A standard HRESULT value.

Example

class CMyDlg : 
   public CAxDialogImpl<CMyDlg>
{
public:
BEGIN_MSG_MAP(CMyDlg)
   MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog)
   COMMAND_HANDLER(IDOK, BN_CLICKED, OnClickedOK)
   COMMAND_HANDLER(IDCANCEL, BN_CLICKED, OnClickedCancel)
   CHAIN_MSG_MAP(CAxDialogImpl<CMyDlg>)
END_MSG_MAP()

   LRESULT OnInitDialog(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled)
   {
      CAxDialogImpl<CMyDlg>::OnInitDialog(uMsg, wParam, lParam, bHandled);

      AtlAdviseSinkMap(this, TRUE);

      bHandled = TRUE;
      return 1;  // Let the system set the focus
   }

   // Remainder of class declaration omitted.

See Also

Functions
Connection Point Macros