AtlEvnt.exe sample shows how to creates ATL sinks by using the ATL IDispEventImpl and IDispEventSimpleImpl classes

Visual C++ .NET

Download Atlevntvcnet.exe now

Project Overview

   dispinterface _EventSink
   {

      properties:
      methods:
      [id(1), helpstring("method Tick")] HRESULT Tick([in] long tckcnt);

   }

Steps to implement IDispEventImpl

1. Create a new class derived from IDispEventImpl. You can click New Class on the Insert menu to generate a new class. For each different sink, add an IDispEventImpl class to the inheritance list with a unique ID as the first parameter. The sink class can either be a COM object (as in a composite control) or a class that just derives from IdispEventImpl:

   // Just a sink.
         class CSinkObj : public IDispEventImpl<IDC_OBJ, CSinkObj>
         {
            ...
         }

   -or-

   // COM object that also implements a sink (as in a composite
         // control).
         class ATL_NO_VTABLE CSinkObj :
            public CComObjectRootEx<CComSingleThreadModel>,
            public CComCoClass<CSinkObj, &CLSID_SinkObj>,
            public IDispatchImpl<ISinkObj, &IID_ISinkObj, &LIBID_SINKPROJLib>,
            public IDispEventImpl<IDC_SRCOBJ, CSinkObj>
         {
            ...
         }

2. You can either specify the source interface ID, the type library ID, major and minor version numbers of the type library containing the source interface explicitly as parameters of IdispEventImpl, or use the AtlGetObjectSourceInterface() to extract this information from the type library. Use of AtlGetObjectSourceInterface() requires that the COM object firing the event implement either IProvideClassInfo2 or IPersist*:

   class CSinkObj : public IDispEventImpl<IDC_OBJ, CSinkObj>
         {
            ...
         }

   -or-

   class CSinkObj : public IDispEventImpl<IDC_OBJ, CSinkObj,
            &DIID__EventSink, // Source interface GUID.
            &LIBID_COMOBJLib, // typelib ID containing source interface.
            1,                // Major version # of LIBID_COMOBJLib.
            0>                // Minor version # of LIBID_COMOBJLib.
         {
            ...
         }

3. Add a sink map to the above class and a sink entry corresponding to each event of a source interface that you would like to handle. Use SINK_ENTRY_EX() when the source interface is specified as a parameter in IDispEventImpl, otherwise, use SINK_ENTRY():

   class CSinkObj : public IDispEventImpl<IDC_SRCOBJ, CSinkObj>
         {
         public:
            BEGIN_SINK_MAP(CSinkObj)
               SINK_ENTRY(IDC_SRCOBJ, 1 /*DISPID*/, OnTick /*Event Handler*/)
            END_SINK_MAP()
            ...
         }

   -or-

   class CSinkObj : public IDispEventImpl<IDC_OBJ, CSinkObj,
                                 &DIID__EventSink, &LIBID_COMOBJLib, 1, 0>
         {
         public:
            BEGIN_SINK_MAP(CSinkObj)
               SINK_ENTRY_EX(IDC_SRCOBJ, DIID__EventSink, 1, OnTick)
            END_SINK_MAP()
            ...
         }

4. Add event handler methods to your class. Make sure they have the __stdcall calling convention:

   class CSinkObj : public IDispEventImpl<IDC_SRCOBJ, CSinkObj3>
         {
         public:
            BEGIN_SINK_MAP(CSinkObj)
               SINK_ENTRY(IDC_SRCOBJ, 1 , OnTick)
            END_SINK_MAP()
   
   
            // event handler for event defined in idl as
            // [id(1)] HRESULT Tick([in] long tckcnt);
            HRESULT __stdcall OnTick(long tickcnt)
            {
               ATLTRACE("CSinkObj::OnTick\n");
               return S_OK;
            }
            ...
         }

5. Connect the sink to the COM object by calling DispEventAdvise(). If the source interface is specified as a parameter to IDispEventImpl then call:

   // pUnk is the IUnknown pointer of the COM object that fires events.
      // pSinkObj is an instance of the CSinkObj class.
         pSinkObj->DispEventAdvise(pUnk);

   or else call:

   // Make sure the COM object corresponding to pUnk implements
         // IProvideClassInfo2 or IPersist*.
         // Call this method to extract info about source type library if you
         // specified only two parameters to IdispEventImpl.
         AtlGetObjectSourceInterface(pUnk, &pSinkObj->m_libid,
            &pSinkObj->m_iid, &pSinkObj->m_wMajorVerNum,
            &pSinkObj->m_wMinorVerNum);
   
         hr = pSinkObj->DispEventAdvise(pUnk, &pSinkObj->m_iid);

6. Disconnect the sink by calling DispEventUnadvise():

   pSinkObj->DispEventUnadvise(pUnk);

Steps to implement IDispEventSimpleImpl

1. Create a class derived from IDispEventSimpleImpl. The source interface has to be specified.
2. Follow step 3 above except add SINK_ENTRY_INFO() for each method of a source interface that you would like to handle. Since IDispEventSimpleImpl does not have access to the type library you have to provide information about each event handler through an _ATL_FUNC_INFO structure, one for each event handler.
   
   Instead of specifying an _ATL_FUNC_INFO structure in SINK_ENTRY_INFO(), you can use the SINK_ENTRY_EX() macro and override the virtual function GetFuncInfoFromId() to fill in the _ATL_FUNC_INFO structure, as shown in the following code.
3. Follow steps 4 through 6 from above:

   static _ATL_FUNC_INFO OnTickInfo = {
            CC_STDCALL,   // Calling convention.
            VT_I4,        // Return type.
            1,            // Number of arguments.
            {VT_I4}       // Argument types.
         };
   
         class CSinkObj :
            public IDispEventSimpleImpl<IDC_SRCOBJ, CSinkObj,
                   &DIID__EventSink>
         {
         public:
         BEGIN_SINK_MAP(CSinkObj)
            SINK_ENTRY_INFO(IDC_SRCOBJ, DIID__EventSink, 1, OnTick,
                            &OnTickInfo)
         END_SINK_MAP()
   
            HRESULT __stdcall OnTick(long tickcnt)
            {
               ATLTRACE("CSinkObj::OnTick\n");
               return S_OK;
            }
            ...
   
         }

   -or-

   class CSinkObj :
            public IDispEventSimpleImpl<IDC_SRCOBJ, CSinkObj,
                   &DIID__EventSink>
         {
         public:
         BEGIN_SINK_MAP(CSinkObj4)
            SINK_ENTRY_EX(IDC_SRCOBJ, DIID__EventSink, 1, OnTick)
            // Equivalent to:
            // SINK_ENTRY_INFO(IDC_SRCOBJ, DIID__EventSink, 1, OnTick, NULL)
         END_SINK_MAP()
   
            HRESULT GetFuncInfoFromId(const IID& iid, DISPID dispidMember,
               LCID lcid, _ATL_FUNC_INFO& info)
            {
               if (InlineIsEqualGUID(iid, DIID__EventSink))
               {
                  info.cc = CC_STDCALL;
                  switch(dispidMember)
                  {
                     case 1:
                        info.vtReturn = VT_I4;
                        info.nParams = 1;
                        info.pVarTypes[0] =  VT_I4;
                        return S_OK;
   
                     default:
                        return E_FAIL;
                  }
               }
               return E_FAIL;
            }
   
            HRESULT __stdcall OnTick(long tickcnt)
            {
               ATLTRACE("CSinkObj::OnTick\n");
               return S_OK;
            }
            ...
         }