Support idispeventimpl-(use of COM events)

Support idispeventimpl

The template class idispeventimpl can be used to provide support for connection point receivers in the ATL class. The connection point receiver enables the class to process events triggered from an external COM object. These connection point receivers are mapped by event receipt ing (provided by the class.

To correctly implement the class connection point receiver, follow these steps:

• Import a Type Library for each External Object
• StatementIdispeventimplInterface
• Declare event receipt ing
• Notification and cancel notification connection points

The steps involved in implementing the connection point receiver are only completed by modifying the Class header file (. h.

Import Type Library

For each external object that you want to process its events, you must import the Type Library. This step defines the events that can be processed and provides the information used when declaring the event to receive ing. You can use the # import command to complete this task. In the Class header file (. h), add the required# ImportCommand line.

The following example imports an external COM server (MyServer) Type Library:

#import "D://MyServer.dll" raw_interfaces_only, no_namespace, named_guids

Note:Each external type library to be supported must have a separate# ImportStatement.

Declare the idispeventimpl Interface

You have imported the Type Library of each scheduling interface. Now you need to declareIdispeventimplInterface. Modify the class declaration and add oneIdispeventimplInterface declaration. For more information about parameters, see idispeventimpl.

The following Code declares two connection point receivers, one for customIExtEvents1AndIExtEvents2Interface.CMyObjClass implementation COM Object:

public IDispEventImpl<0, CMyObj, &DIID__IExtEvents1,
    &LIBID_EXTEVENTS1Lib, 1, 0>,
public IDispEventImpl<1, CMyObj, &DIID__IExtEvents2,
    &LIBID_EXTEVENTS2Lib, 1, 0>

Declare event receipt ing

To enable event notification to be processed by the correct function, the class must route each event to its correct handler. This is achieved by declaring an event receipt ing.

ATL provides several macros that make this ing easier: begin_sink_map, end_sink_map, and sink_entry. The standard format is as follows:

BEGIN_SINK_MAP(comClass)
   SINK_ENTRY(id, dispid, func)
   . . . //additional external event entries
END_SINK_MAP()

The following example uses two event handlers to declare an event receipt ing:

BEGIN_SINK_MAP(CMyObj)
   SINK_ENTRY(0, Events1, OnClick1)
   SINK_ENTRY(0, Events2, OnClick2)
END_SINK_MAP()

Implementation is nearing completion. The last step involves the external interface for notification and cancellation.

Notify and cancel the idispeventimpl Interface

The last step is to implement a method for notifying (or canceling) All connection points at the appropriate time. This notification must be completed before communication between the external client and the object can occur. Before the object becomes visible, the output interface is queried from each external scheduling interface supported by the object. Create a connection and use the reference to the output interface to process events from the object. This process is called "notification ".

After an object uses an external interface, it should be notified that the output interface is no longer used by the class. This process is called "cancellation notification ".

Because of the unique characteristics of COM objects, the specific details and execution of this process vary with implementations. These details are beyond the scope of this topic and will not be discussed.