Invoking a Custom Agent

The following steps illustrate folder event processing and refer to elements in the diagram in the previous section. In this example, "Folder 3" is one of several folders configured to monitor events. The creation of the agents for this folder linked certain events that occur in Folder 3 to a script placed in Folder 3.

Although the usual case when an event occurs is for a script to be run, custom agents can also be used. This is because The Microsoft Exchange Event Service can pass an event to any agent that exposes the COM interface IExchangeEventHandler.

1. A message is posted to Folder 3, a folder being monitored by the Event Service.
2. A notification of the posting is sent to the Event Service.
3. The Event Service calls an Incremental Change Synchronization (ICS) method to request all the changes to Folder 3 that have occurred since the last time an event occurred in that folder.
4. ICS generates and sends the change list to the Event Service. This list contains the message identifier of the message just posted and any other changed messages—including new, changed, and deleted messages.
5. The Event Service searches the monitored folder for agents.
6. The Event Service requests the agent for the CLSID of its handler.
7. The Event Service calls CoCreateInstance to create an object of that CLSID.
8. The Event Service performs a QueryInterface for the IExchangeEventHandler interface.
9. Once the Event Service has retrieved the IExchangeEventHandler interface on the object, it writes session, folder, and message information into properties in a Microsoft Exchange EventSource object, which provides an implementation of the IEventSource interface. The Event Service also sets the event type (new message, changed message, deleted message, timer event) in a property for the EventSource object.
10. The Event Service calls IExchangeEventHandler::ExecuteEvent, passing the IEventSource interface exposed on the new EventSource object.
11. Using the IEventSource interface passed from the Event Service, the custom handler retrieves event information and responds.