ATL Event Handling Summary
In general, handling COM events is a relatively simple process. There are three main steps:
Implement the event interface on your object.
Advise the event source that your object wants to receive events.
Unadvise the event source when your object no longer needs to receive events.
Implementing the Interface
There are four main ways of implementing an interface using ATL.
| Derive from | Suitable for Interface type | Requires you to implement all methods* | Requires a type library at run time |
|---|---|---|---|
| The interface | Vtable | Yes | No |
| IDispatchImpl | Dual | Yes | Yes |
| IDispEventImpl | Dispinterface | No | Yes |
| IDispEventSimpleImpl | Dispinterface | No | No |
* When using ATL support classes, you are never required to implement the IUnknown or IDispatch methods manually.
Advising and Unadvising the Event Source
There are three main ways of advising and unadvising an event source using ATL.
| Advise function | Unadvise function | Most suitable for use with | Requires you to keep track of a cookie | Comments |
|---|---|---|---|---|
| AtlAdvise, CComPtrBase::Advise | AtlUnadvise | Vtable or dual interfaces | Yes | AtlAdvise is a global ATL function. CComPtrBase::Advise is used by CComPtr and CComQIPtr. |
| IDispEventSimpleImpl::DispEventAdvise | IDispEventSimpleImpl::DispEventUnadvise | IDispEventImpl or IDispEventSimpleImpl | No | Fewer parameters than AtlAdvise since the base class does more work. |
| CComCompositeControl::AdviseSinkMap(TRUE) | CComCompositeControl::AdviseSinkMap(FALSE) | ActiveX controls in Composite controls | No | CComCompositeControl::AdviseSinkMap advises all entries in the event sink map. The same function unadvises the entries. This method is called automatically by the CComCompositeControl class. |
| CAxDialogImpl::AdviseSinkMap(TRUE) | CAxDialogImpl::AdviseSinkMap(FALSE) | ActiveX controls in a dialog box | No | CAxDialogImpl::AdviseSinkMap advises and unadvises all ActiveX controls in the dialog resource. This is done automatically for you. |