Transport and Protocol Events

Besides programming to database events, you can also write to events at the transport and protocol event level. Before we discuss writing to these events, I want to point out that I highly recommend that you write to these events using C++, although you can use languages compatible with .NET as well if you have to. The reason for this is that with certain events, specifically transport events, your event handler will process every message that goes through the system, both internally and externally delivered. This means poorly written code or code written with an interpreted language such as a scripting language can seriously affect the performance of your Exchange servers. For this reason, only a single event is exposed to non-C++ developers such as script or Visual Basic developers. I'll describe this event as well as the architecture for the overall transport and protocol event architecture. You can write more complex event handlers using C++ (because of the numerous transport and protocol events), but that topic is beyond the scope of this book. The Exchange SDK has good documentation on this topic and also has new information on writing managed code event handlers. The SDK even includes a Primary Interop Assembly for transport and protocol events that you can download.

Transport and Protocol Event Architecture

Figure 17-9 depicts where and when transport and protocol events occur. As you can see, transport events occur when communication between client and server takes place over that protocol. For example, when an Internet-based client or a remote SMTP system starts a new SMTP session with an Exchange server, the server fires a new event that tells you a new SMTP command is inbound. You can then capture that command and perform whatever processing you need. Transport events occur when messages flow through the system, whether they need to be locally or remotely delivered.

Figure 17-9: The relationship between transport and protocol events

We will discuss only event handlers that you can write in Visual Basic or VBScript, so we need to look at the transport events. Figure 17-10 depicts the architecture for transport events.

Figure 17-10: The system flow for transport events

You will notice a CDO_OnArrival event. This event is a CDO wrapper around the OnArrival event so that programmers using Visual Basic or a scripting language can handle this event. This event fires when an e- mail message is received at the server. The event has the following definition:

 Sub ISMTPOnArrival_OnArrival(ByVal Msg As CDO.Message, _                              EventStatus As CDO.CdoEventStatus) 

You are passed the message as a CDO message, and you need to set the EventStatus to one of two values: CdoRunNextSink (0) or CdoSkipRemainingSinks (1) . Depending on what you do in your code, you will either allow lower-priority event sinks to run or you will stop them from running. The following example shows how you can write to the CDO OnArrival event using Visual Basic. With Visual Basic, you should implement the IsCacheable interface so the SMTP service will cache your DLL into memory and will not have to load it from disk. With scripting languages, this is not the case, so you do not have to implement this interface because the script will always be interpreted by the server. The following example just writes out information about the message to a text file:

 Implements CDO.ISMTPOnArrival Implements IEventIsCacheable      Private Sub IEventIsCacheable_IsCacheable()     'Just implement the interface so we're cached End Sub      Private Sub ISMTPOnArrival_OnArrival(ByVal Msg As CDO.Message, _                                      EventStatus As CDO.CdoEventStatus)          Dim ofs As New Scripting.FileSystemObject     Dim oFile As Scripting.TextStream     Set oFile = ofs.OpenTextFile("c:\MsgLog.txt", ForAppending, True )     oFile.Write "From: " & Msg.From & vbCrLf     oFile.Write "To: " & Msg.To & vbCrLf     oFile.Write "Subject: " & Msg.Subject & vbCrLf & vbCrLf     oFile.Write Msg.TextBody & vbCrLf & vbCrLf     oFile.Close     EventStatus = cdoRunNextSink End Sub 

Registering Your Event Handler

As with database events, you must register with the system that you want to handle the OnArrival event. The difference between database event registrations and transport event registrations is that the latter are stored in the IIS metabase and database event registrations are stored in the Exchange information store. Therefore, you must write to the metabase to create your transport or protocol event registrations. Luckily, you find a program called smtpreg.vbs (or nntpreg.vbs for NNTP events) in the Exchange SDK. This file includes code to register, enumerate, and unregister your event handlers. You can also pass protocol rules so that your event handler is not called for every message sent to the server, just specific messages. Be sure to put your protocol rules in quotes on the command line. To get the best information about the .vbs files, just run them and pass along the command line a /? command. The following code registers an event handler for the OnArrival CDO event on the first SMTP virtual server in IIS for a DLL called MyEventHandler.MySink to process every e-mail message coming into the system:

 cscript smtpreg.vbs / add 1 onarrival MyDisplayName MyEventHandler.MySink  "mail from=*" 

Advanced Considerations

If you have never heard about the Transport Neutral Encapsulation Format (TNEF), you might want to conduct some research on it before you write event handlers. When you send mail between internal servers in an Exchange organization via Outlook or OWA, all mail, including the body, attachments, and custom properties, is stored in TNEF. Therefore, if you register an event handler for the OnArrival event and you get one of these messages, you will not be able to look at the body or the attachments because they are TNEF encoded. So, here's a best practice. If you need to modify the body or attachments of mail sent entirely within your system, you can write to the database events we discussed earlier. These events pass the right content to you ”you do not have to worry about the original format that the content came in (whether it was Multipurpose Internet Mail Extensions [MIME] or TNEF).

If you want to process e- mails and want to affect the content of the messages, your best bet is to run your transport event handlers on your border SMTP servers. Mail coming in from or going out to other systems will probably not be in TNEF, but rather MIME or plain text. CDO can parse the format, and your event handler can modify the content of the messages.

For the not faint of heart, there are TNEF APIs that you can use to decode and encode TNEF. MSDN has a TNEF decoder sample, but it's written entirely in C++; if it does not meet your needs, you would have to rewrite portions of it.