README.TXT

Custom Message Event Extension 
 
 
SUMMARY 
======= 
 
The Events.Ext sample demonstrates how to implement a custom message event 
extension for the Microsoft Exchange Client. In particular, it demonstrates: 
 
  - reading message text before displayed in the read note form 
  - reading message text as it is submitted to MAPI 
 
This sample uses a very basic form of signing a message. A checksum on the 
message as it is written is stored as a custom property. Upon reading the 
message, the extension verifies the checksum and displays one of two 
possible outcomes: the message has been verified with correct contents, or 
the message text has been altered. 
 
MORE INFORMATION 
================ 
 
This sample requires Microsoft Windows NT 3.51 or Windows 95, the MAPI 1.0 
(Extended MAPI) PDK (Build 410 or above),  Microsoft Visual C++ version 2.0 
(or later), and the Win32 SDK for Windows NT and Windows 95. 
 
Configuration 
------------- 
 
To configure Exchange to use the client extension, place the following 
REG_SZ entry in the system registry in: 
HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Client\Extensions 
 
    Samp Ext=4.0;C:\MAPISAMP\EVENTEXT\EVEXT32.DLL;1;00000111111100 
 
You can leave out an explicit path to EVEXT32.DLL if it resides in a 
directory listed in the system PATH. 
 
Exchange client extensions are designed using OLE's Component Object Model. 
The client calls methods which are provided in the extension. In some calls 
to the extension interface, a pointer to a callback interface 
(IExchExtCallback) is given for the extension to call back into the 
Exchange client. For more information read "Extending the Microsoft Exchange 
Client" in the MAPI PDK documentation. 
 
This sample extension includes the implementation of a property page 
displayed in the Tools Option property sheet to either enable or disable 
signatures. The sample will check a flag before calculating or verifying 
checksums. 
 
GetObject is used during the OnWriteComplete and OnRead methods to obtain 
the message body. The checksum is calculated and written as a custom 
property of a message when the Send button is clicked. The checksum is 
recalculated and verified when a message is read. For large messages, the 
checksum may take a few seconds depending on the size of the message and the 
speed of the machine. 
 
During the case that a message is found to have "altered" text according 
to the checksum, the extension gives the user a choice whether to continue 
to read the message or not. If not, an error return value is set in the 
OnRead method to be used by the OnReadComplete method. Returning 
MAPI_E_CALL_FAILED from OnReadComplete causes Exchange to call OnReadComplete 
again with ulFlags parameter set to an error. The parameter is ignored by 
this sample and returning MAPI_E_CALL_FAILED causes Exchange to not display 
the read note form. 
 
This sample also supports the "Reply to Sender" context and signs the 
reply when enabled. Replying to a non-signed message while the signatures 
are enabled adds a signature to the entire message, counting original 
message and reply. Replying to a signed message while the signature is 
disabled removes the original signature. 
 
The logic for signing is only calculating the checksum on the PR_BODY 
message property. The extension does not take "quirks" of certain providers 
into its logic and the extension will interpret that a message was "altered" 
when in fact it has not. Two examples are the MSPERR Transport and the MSMail 
provider. With the MSPeer transport, it will add the text 
"*** End of message ***" at the end of the message. The checksum does not 
include this upon sending. The MSMail provider strips whitespace at the end 
of a line just before the carriage return characters (CRLF). When sending, 
the checksum calculation includes the whitespace. So the checksum verification 
upon reading will not match with the stored checksum property. If you write a 
message without placing any spaces just before a carriage return, or just 
allow the richedit control wordwrap, the checksums will be equal.