Implementing SMTP Event Sinks
Topic Last Modified: 2004-06-08
To implement a Simple Mail Transfer Protocol (SMTP) OnArrival event sink, follow this procedure:
Create a Component Object Model (COM) class that implements the ISMTPOnArrival interface. You can do this using any programming language or scripting language that supports COM. For more information about using scripting languages to implement this interface, see Implementing Sinks with Scripting Languages.
For performance reasons, you can allow the source to cache the sink for subsequent use. In this case, implement the IEventIsCacheable interface. This interface consists of the IsCacheable method and should return the HRESULT value S_OK. When the event dispatcher thread creates an instance of the sink COM class, it calls QueryInterface for this interface, and calls the IsCacheable method. If the value S_OK is returned, it will cache the sink for subsequent events and an instance of the sink COM class need not be recreated for each event. The type information for the IEventIsCacheable interface is located in the Server Extension Objects (SEO) COM dynamic-link library (DLL), SEO.DLL. (The type library is a resource in the DLL.)
Register the COM class on the local server. The event dispatcher will use either the programmatic identifier or the class identifier (CLSID) for the class to create a class instance when an event occurs. For scripts, you must register the Microsoft® Collaboration Data Objects (CDO) scripting host as the sink and configure it with the location of your script. See Implementing Sinks with Scripting Languages.
Register a binding for the SMTP OnArrival event using the Server Extension Objects (SEO) or the smtpreg.vbs command-line Windows Script Host (WSH) script. See Managing Event Bindings.
When the event dispatcher calls the ISMTPOnArrival.OnArrival method on your sink, it is passed an IMessage interface on a Message object that is bound to an ADO Stream object. The Stream object contains the message content within the transport itself. Modifications to the message content must therefore be saved to the transport Stream object by calling the IDataSource.Save method on the Message object.
Additionally, the IMessage.EnvelopeFields collection contains the message's transport envelope fields. All fields within this collection reside in the http://schemas.microsoft.com/cdo/smtpenvelope/ namespace. (Only Message objects passed to event sinks have contents in the IMessage.EnvelopeFields collection.) The message can be examined and modified by your sink. For information, see Using the SMTP Message Envelope Fields.