ch12.htm

MAPI__SAPI__TAPI

</p>

<p align="center"><b>Table 12.2 The Windows Messaging client COM interfaces.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Microsoft Exchange COM Interface</i></td>
    <td WIDTH="318"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExt:Iunknown</font></tt> </td>
    <td WIDTH="318">Can be used to load extension objects in all contexts. Most extension 
    objects are designed to operate only within a particular context or set of contexts, but 
    some can operate in all contexts. Use this primarily in conjunction with the <tt><font
    FACE="Courier">IExchExtCallBack</font></tt> interface. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtAdvancedCriteria</font></tt> </td>
    <td WIDTH="318">Used to enable extension objects to replace or enhance the functionality 
    of the Advanced dialog box that appears when the user selects the <tt><font FACE="Courier">Advanced</font></tt> 
    button from the Find dialog box. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtAttachedFileEvents</font></tt> </td>
    <td WIDTH="318">Used to enable extension objects to replace or enhance the default 
    attachment-handling behavior of Microsoft Exchange. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtCallBack</font></tt> </td>
    <td WIDTH="318">Enables extension objects to retrieve information about the current 
    context. <tt><font FACE="Courier">IExchExtCallBack</font></tt> uses the methods of the <tt><font
    FACE="Courier">IUnknown</font></tt> interface for reference management. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtCommands</font></tt> </td>
    <td WIDTH="318">Used by extension objects to add and execute custom menu or toolbar 
    command buttons. Extension objects can also replace existing Microsoft Exchange commands 
    or enhance their behavior before Microsoft Exchange carries them out. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtMessageEvents</font></tt> </td>
    <td WIDTH="318">Used by extension objects to give them the ability to replace or enhance 
    the default message-handling behavior of Microsoft Exchange. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtPropertySheets</font></tt> </td>
    <td WIDTH="318">Used to enable extension objects to append pages to Microsoft Exchange 
    property sheets. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtSessionEvent</font></tt> </td>
    <td WIDTH="318">Used to enable an extension object to respond to the arrival of new 
    messages. Use this interface to build custom inbox processing routines. </td>
  </tr>
  <tr>
    <td WIDTH="272"><tt><font FACE="Courier">IExchExtUserEvents</font></tt> </td>
    <td WIDTH="318">Used to enable an extension object to handle changes to the currently 
    selected list box item, text, or object. </td>
  </tr>
</table>
</center></div>

<p>Most of the COM interfaces are self-explanatory. However, a few deserve some extra 
attention. The <tt><font FACE="Courier">IExchExt:IUnknown</font></tt> interface is used 
mostly by the <tt><font FACE="Courier">IExchExtCallBack</font></tt> interface. Although it 
is possible to build complete context interfaces using <tt><font FACE="Courier">IExchExt:IUnknown</font></tt>, 
it's not very practical-especially when you have all the other COM objects to work with. </p>

<p>Also, the <tt><font FACE="Courier">IExchExtUserEvents</font></tt> interface returns 
general information about user actions in the Windows Messaging client. Whenever the focus 
changes from one Microsoft Exchange object to another (that is, the selected folder or 
message), you can have your application execute some code. </p>

<p>Finally, there are two other interfaces not listed in Table 12.2. The <tt><font
FACE="Courier">IExchExtModeless:IUnknown</font></tt> and <tt><font FACE="Courier">IExchExtModelessCallBack</font></tt> 
interfaces can be used to develop non-modal processes that run alongside the Windows 
Messaging client and intercept messages normally addressed to the client. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td WIDTH="547"><blockquote>
      <p>Creating modeless add-ins is beyond the scope of this book. If you're interested in 
      creating a modeless extension for Microsoft Exchange, you can find additional information 
      in the Microsoft MAPI SDK documentation.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="MappingContextstoCOMInterfaces"><b>Mapping Contexts to COM Interfaces</b></a></h3>

<p>In order to write your program to become active for the various contexts, you need to 
use one (or more) of the Component Object Model interfaces that match up to the Microsoft 
Exchange contexts. In other words, you &quot;map&quot; your program code to contexts using 
the COM interfaces. When you register your program with one or more of the COM interfaces, 
your program receives alerts from Microsoft Exchange that fire off methods within the COM 
interface. You can place code within these methods to make sure that your program performs 
the desired actions at the right time. </p>

<p>For example, if you want your program to execute whenever the <tt><font FACE="Courier">SESSION</font></tt> 
context occurs, you'll need to use the <tt><font FACE="Courier">IExchExtSession</font></tt> 
COM interface object in your program. Some of the contexts can be accessed using more than 
one COM interface. For example, The <tt><font FACE="Courier">IExchExtMessage</font></tt> 
COM interface is called from several of the Microsoft Exchange contexts (<tt><font
FACE="Courier">SENDNOTEMESSAGE</font></tt>, <tt><font FACE="Courier">READNOTEMESSAGE</font></tt>, 
<tt><font FACE="Courier">SENDPOSTMESSAGE</font></tt>, <tt><font FACE="Courier">READPOSTMESSAGE</font></tt>, 
<tt><font FACE="Courier">READREPORTMESSAGE</font></tt>, and <tt><font FACE="Courier">SENDRESENDMESSAGE</font></tt>). 
To make it a bit more complex, a single context can alert more than one COM interface. For 
example, the <tt><font FACE="Courier">ADDRBOOK</font></tt> context notifies the <tt><font
FACE="Courier">IExchExtCommands</font></tt>, <tt><font FACE="Courier">IExchExtUserEvents</font></tt>, 
and <tt><font FACE="Courier">IExchExtPropertySheets</font></tt> interfaces. </p>

<p>Table 12.3 shows the Microsoft Exchange contexts along with the COM interfaces that can 
be used to monitor those contexts.<br>
</p>

<p align="center"><b>Table 12.3. Mapping Microsoft Exchange contexts to Microsoft Exchange 
COM interfaces.<br>
</b></p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Context Name</i></td>
    <td WIDTH="304"><i>Interfaces Called</i> </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">TASK</font></tt></td>
    <td WIDTH="304">None. Only <tt><font FACE="Courier">IexchExt::Install</font></tt> and <tt><font
    FACE="Courier">IUnknown::Release</font></tt> are called from this context. </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">SESSION</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtSessionEvents</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">VIEWER</font></tt>, <tt><font FACE="Courier">REMOTEVIEWER</font></tt>, 
    </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtCommands</font></tt>, <tt><font
    FACE="Courier">IExchExtUserEvents</font></tt>, </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">SEARchVIEWER</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtPropertySheets</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">ADDRBOOK</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtCommands</font></tt>, <tt><font
    FACE="Courier">IExchExtUserEvents</font></tt>, <tt><font FACE="Courier">IExchExtPropertySheets</font></tt> 
    </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">SENDNOTEMESSAGE</font></tt>, </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtCommands</font></tt>, <tt><font
    FACE="Courier">IExchExtUserEvents</font></tt>, </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">READNOTEMESSAGE</font></tt>, </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtMessageEvents</font></tt>, </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">READREPORTMESSAGE</font></tt>, </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtAttachedFileEvents</font></tt>, </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">SENDRESENDMESSAGE</font></tt>, <br>
    <tt><font FACE="Courier">READPOSTMESSAGE</font></tt>,<br>
    <tt><font FACE="Courier">SENDPOSTMESSAGE</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtPropertySheets</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">PROPERTYSHEETS</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtPropertySheets</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="226"><tt><font FACE="Courier">ADVAncEDCRITERIA</font></tt> </td>
    <td WIDTH="304"><tt><font FACE="Courier">IExchExtAdvancedCriteria</font></tt> </td>
  </tr>
</table>
</center></div>

<p>Now that you have a good idea of how the Windows Messaging client extensions and the 
Windows Messaging client contexts work together, it's time to focus on two of the COM 
interfaces that you'll use in the Message Signing project for this chapter: 

<ul>
  <li><font COLOR="#000000">The </font><tt><font FACE="Courier">Message Events</font></tt> 
    interface </li>
  <li><font COLOR="#000000">The </font><tt><font FACE="Courier">Property Sheets</font></tt> 
    interface </li>
</ul>

<h3><a NAME="MessageEventExtensions"><b>Message Event Extensions</b></a> </h3>

<p>These message event extensions can be used to monitor the Windows Messaging client 
actions on incoming and outgoing messages. When your application registers the <tt><font
FACE="Courier">IExchExtMessageEvents</font></tt> interface, you can receive notifications 
whenever the user attempts to read, write, address, or submit a MAPI message. Table 12.4 
shows the methods associated with the <tt><font FACE="Courier">IExchExtMessageEvents</font></tt> 
interface along with a short description.<br>
</p>

<p align="center"><b>Table 12.4. The methods of the <tt><font FACE="Courier">IExchExtMessageEvents</font></tt> 
interface.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Interface Method</i></td>
    <td WIDTH="376"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnCheckNames</font></tt> </td>
    <td WIDTH="376">Used to replace or enhance the behavior of Microsoft Exchange when 
    recipient names typed by the user are being resolved to their address book entries. </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnCheckNamesComplete</font></tt> </td>
    <td WIDTH="376">Used to roll back the implementation of the <tt><font FACE="Courier">OnCheckNames</font></tt> 
    method in case of an error, or to release resources allocated by <tt><font FACE="Courier">OnCheckNames</font></tt>. 
    </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnRead</font></tt> </td>
    <td WIDTH="376">Used to replace or enhance the behavior of Microsoft Exchange when reading 
    information from a message. </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnReadComplete</font></tt> </td>
    <td WIDTH="376">Used to roll back implementation of the <tt><font FACE="Courier">OnRead</font></tt> 
    method in case of an error or to release resources allocated by <tt><font FACE="Courier">OnRead</font></tt>. 
    </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnSubmit</font></tt> </td>
    <td WIDTH="376">Used to replace or enhance the behavior of Microsoft Exchange when a 
    message is being submitted. </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnSubmitComplete</font></tt> </td>
    <td WIDTH="376">Used to roll back implementation of the <tt><font FACE="Courier">OnSubmit</font></tt> 
    method in case of an error, or to release resources allocated by <tt><font FACE="Courier">OnSubmit</font></tt>. 
    </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnWrite</font></tt> </td>
    <td WIDTH="376">Used to replace or enhance the behavior of Microsoft Exchange when writing 
    information to a message. </td>
  </tr>
  <tr>
    <td WIDTH="214"><tt><font FACE="Courier">OnWriteComplete</font></tt> </td>
    <td WIDTH="376">Used to roll back implementation of the <tt><font FACE="Courier">OnWrite</font></tt> 
    method in case of an error, or to release resources allocated by <tt><font FACE="Courier">OnWrite</font></tt>. 
    </td>
  </tr>
</table>
</center></div>

<p>You should notice that all eight of the message event methods can be sorted into four 
groups of two: 

<ul>
  <li><tt><font FACE="Courier">OnCheckNames</font></tt>/<tt><font FACE="Courier">OnCheckNamesComplete</font></tt> 
  </li>
  <li><tt><font FACE="Courier">OnRead</font></tt>/<tt><font FACE="Courier">OnReadComplete</font></tt> 
  </li>
  <li><tt><font FACE="Courier">OnSubmit</font></tt>/<tt><font FACE="Courier">OnSubmitComplete</font></tt> 
  </li>
  <li><tt><font FACE="Courier">OnWrite</font></tt>/<tt><font FACE="Courier">OnWriteComplete</font></tt> 
  </li>
</ul>

<p>The first method of the pair (for example, <tt><font FACE="Courier">OnWrite</font></tt>) 
is called when the user attempts the suggested operation within the Windows Messaging 
client. The second method of the pair (for example, <tt><font FACE="Courier">OnWriteComplete</font></tt>) 
is executed immediately after the first method. This second event can be used to check 
results from code execution under the first method, and to perform any error recovery or 
cleanup that might be needed. </p>

<p>For example, if you decide to add an extension that encrypts messages upon submission