ch12.htm

MAPI__SAPI__TAPI

for delivery, you could write code in the <tt><font FACE="Courier">OnSubmit</font></tt> 
method of the <tt><font FACE="Courier">Message Event</font></tt> interface that would copy 
the message body to a temporary file and convert it into its encrypted form. You might 
then write code in the <tt><font FACE="Courier">OnSubmitComplete</font></tt> method that 
would check the results of the encryption to make sure all went well. If not, you could 
then inform the user of the problem and restore the original text. If all went well, the <tt><font
FACE="Courier">OnSubmitComplete</font></tt> method could copy the encrypted message over 
the original and then erase the temporary file. </p>

<p>In the example you'll build later in this chapter, you'll use the <tt><font
FACE="Courier">OnWrite</font></tt> and <tt><font FACE="Courier">OnRead</font></tt> method 
pairs to create and check message checksums before saving and reading MAPI messages. </p>

<h3><a NAME="PropertyExtensions"><b>Property Extensions</b></a> </h3>

<p>The Windows Messaging client also has an extension for managing the creation of custom 
property pages. You can create a simple dialog box and then register it as one of the 
tabbed property pages of a Windows Messaging client object. The Windows Messaging client 
displays property pages for four different objects. Table 12.5 shows the four objects 
along with short descriptions of them. <br>
</p>

<p align="center"><b>Table 12.5. The Microsoft Exchange objects that display property 
pages.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Property Page Object</i></td>
    <td WIDTH="384"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="206">Information Store Properties</td>
    <td WIDTH="384">This shows the properties of the selected MAPI <tt><font FACE="Courier">Information 
    Store</font></tt> object. </td>
  </tr>
  <tr>
    <td WIDTH="206">Folder Properties</td>
    <td WIDTH="384">This shows the properties of the selected MAPI <tt><font FACE="Courier">Folder</font></tt> 
    object. </td>
  </tr>
  <tr>
    <td WIDTH="206">Message Properties</td>
    <td WIDTH="384">This shows the properties of the selected MAPI <tt><font FACE="Courier">Message</font></tt> 
    object. </td>
  </tr>
  <tr>
    <td WIDTH="206">Tools Options Menu</td>
    <td WIDTH="384">This shows the properties page from the <tt><font FACE="Courier">Tools | 
    Options</font></tt> menu selection of the Windows Messaging client. </td>
  </tr>
</table>
</center></div>

<p>There are three methods to the <tt><font FACE="Courier">IExchExtPropertySheets</font></tt> 
COM interface. These methods allow you to determine the number of pages that are currently 
registered for display, allow you to define and add a new property page, and allow you to 
release the property page you added to the object. Table 12.6 describes the three methods.<br>
</p>

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

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Interface Method</i></td>
    <td WIDTH="424"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="166"><tt><font FACE="Courier">GetMaxPageCount</font></tt> </td>
    <td WIDTH="424">Returns the maximum number of pages an extension will add to the property 
    sheet. </td>
  </tr>
  <tr>
    <td WIDTH="166"><tt><font FACE="Courier">GetPages</font></tt> </td>
    <td WIDTH="424">Adds property sheet page to the current list of pages. </td>
  </tr>
  <tr>
    <td WIDTH="166"><tt><font FACE="Courier">FreePages</font></tt> </td>
    <td WIDTH="424">Frees any resources allocated by the <tt><font FACE="Courier">GetPages</font></tt> 
    method. </td>
  </tr>
</table>
</center></div>

<p>In the project shown later in this chapter, you'll use these three methods to add a 
property page to the <tt><font FACE="Courier">Tools | Options</font></tt> menu of the 
Windows Messaging client. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>The other COM interfaces mentioned here also have associated methods. These methods are 
      not covered in this chapter. This was done to focus on the creation of a complete Windows 
      Messaging client extension application. You can learn more about all the Microsoft 
      Exchange COM interfaces and their methods by reviewing the MAPI SDK documentation.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="RegisteringExtensions"><b>Registering Extensions</b></a> </h3>

<p>Once you have successfully created a Windows Messaging client extension, you must 
inform the Windows Messaging client that the extension exists before it will be able to 
use it. This is done by making entries in the system registry database. All Windows 
Messaging client extensions must be registered. On 32-bit Windows systems, the client 
extension entries are placed in the <tt><font FACE="Courier">HKEY_LOCAL_MAchINE\Software\Microsoft\Exchange\Client\Extensions</font></tt> 
section of the registry. On 16-bit systems, the registration is stored in the [Extensions] 
section of the <tt><font FACE="Courier">EXchNG.INI</font></tt> file. Figure 12.2 shows the 
system registry editor open to the [Extensions] section. </p>

<p><a HREF="f12-2.gif"><b>Figure 12.2 : </b><i>Viewing the Exchange/Client/Extensions 
section of the System Registry.</i></a> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>In network environments, Windows Messaging client extensions can be shared among 
      several clients. Shared Microsoft Exchange DLLs are registered in the <tt><font
      FACE="Courier">SHARED32.INI</font></tt> file on 32-bit systems and in the <tt><font
      FACE="Courier">SHARED.INI</font></tt> file on 16-bit systems. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>The registry entry tells the Windows Messaging client several important things about 
the extension DLL. The syntax of an extension entry is as follows: </p>

<p><tt><font FACE="Courier">Tag=Version;</font><b><font SIZE="1" FACE="Courier">&lt;ExtsDir&gt;</font></b><font
FACE="Courier">DllName;[Ordinal];[ContextMap];[InterfaceMap];[Provider]</font></tt> </p>

<p>Table 12.7 shows each of the parts of the registration entry and explains its meaning 
and use.<br>
</p>

<p align="center"><b>Table 12.7. The Windows Messaging client extension registration 
entry.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Entry Parameter</i></td>
    <td WIDTH="453"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">Tag</font></tt></td>
    <td WIDTH="453">An extension identifier that uniquely distinguishes the registry entry 
    from other entries. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">Version</font></tt> </td>
    <td WIDTH="453">The version number of the syntax. Use 4.0 for the current release of 
    Microsoft Exchange. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">DllName</font></tt> </td>
    <td WIDTH="453">The complete path and filename of the DLL containing the extension. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">Ordinal</font></tt> </td>
    <td WIDTH="453">An optional field that specifies the entry point into the <tt><font
    FACE="Courier">VTable</font></tt> of the DLL to retrieve the extension object. If this 
    field is empty, the default value is <tt><font FACE="Courier">1</font></tt>. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">ContextMap</font></tt> </td>
    <td WIDTH="453">An optional string made up of &quot;0&quot; and &quot;1&quot; characters 
    that indicate the contexts in which the extension should be loaded. Any unspecified values 
    after the end of the string are assumed to be zero. If no context map is provided, the 
    extension is loaded in all contexts. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">InterfaceMap</font></tt> </td>
    <td WIDTH="453">An optional string made up of &quot;0&quot; and &quot;1&quot; characters 
    that indicates the interfaces the extension supports. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">Provider</font></tt> </td>
    <td WIDTH="453">An optional string containing the <tt><font FACE="Courier">PR_SERVICE_NAME</font></tt> 
    of the service provider that your extension is designed to work with. For example, if your 
    extension is designed to work with a custom address book provider, this entry would 
    contain the <tt><font FACE="Courier">PR_SERVICE_NAME</font></tt> of the address book 
    provider. You should only use this parameter if your extension is provider-specific. </td>
  </tr>
</table>
</center></div>

<p>The <tt><font FACE="Courier">ContextMap</font></tt> and <tt><font FACE="Courier">InterfaceMap</font></tt> 
entries need some clarification. By placing &quot;1&quot; or &quot;0&quot; values in these 
strings, you are telling Microsoft Exchange which context events and COM interfaces you 
want your client to participate in. Table 12.8 shows the meaning of each position in the <tt><font
FACE="Courier">ContextMap</font></tt> parameter.<br>
</p>

<p align="center"><b>Table 12.8. The <tt><font FACE="Courier">ContextMap</font></tt> 
parameter positions.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Parameter Position</i></td>
    <td WIDTH="186"><i>Context</i> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">1</td>
    <td WIDTH="186"><tt><font FACE="Courier">SESSION</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">2</td>
    <td WIDTH="186"><tt><font FACE="Courier">VIEWER</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">3</td>
    <td WIDTH="186"><tt><font FACE="Courier">REMOTEVIEWER</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">4</td>
    <td WIDTH="186"><tt><font FACE="Courier">SEARchVIEWER</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">5</td>
    <td WIDTH="186"><tt><font FACE="Courier">ADDRBOOK</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">6</td>
    <td WIDTH="186"><tt><font FACE="Courier">SENDNOTEMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">7</td>
    <td WIDTH="186"><tt><font FACE="Courier">READNOTEMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">8</td>
    <td WIDTH="186"><tt><font FACE="Courier">SENDPOSTMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">9</td>
    <td WIDTH="186"><tt><font FACE="Courier">READPOSTMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">10</td>
    <td WIDTH="186"><tt><font FACE="Courier">READREPORTMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">11</td>
    <td WIDTH="186"><tt><font FACE="Courier">SENDRESENDMESSAGE</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">12</td>
    <td WIDTH="186"><tt><font FACE="Courier">PROPERTYSHEETS</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">13</td>
    <td WIDTH="186"><tt><font FACE="Courier">ADVAncEDCRITERIA</font></tt> </td>
  </tr>
  <tr>
    <td WIDTH="143"><p align="center">14</td>
    <td WIDTH="186"><tt><font FACE="Courier">TASK</font></tt> </td>
  </tr>
</table>
</center></div>

<p>For example, if your DLL extension should execute each time one of the message events 
occurred, you would create the following <tt><font FACE="Courier">ContextMap</font></tt> 
parameter: </p>

<p><tt><font FACE="Courier">&quot;00000111111000&quot;</font></tt> </p>

<p>In addition to the <tt><font FACE="Courier">ContextMap</font></tt> parameter, there is 
a parameter to inform Microsoft Exchange which COM interfaces your extension will use. 
Table 12.9 shows the list of COM interfaces and their positions in the <tt><font
FACE="Courier">InterfaceMap</font></tt> parameter.<br>
</p>