ch10.htm

MAPI__SAPI__TAPI

    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>So there are the three key points to remember about the differences between e-mail and 
discussion messages: 

<ul>
  <li><font COLOR="#000000">Discussion messages are addressed to folders, not people.</font> </li>
  <li><font COLOR="#000000">MAPI uses the </font><tt><font FACE="Courier">ConversationTopic</font></tt> 
    and <tt><font FACE="Courier">ConversationIndex</font></tt> properties to keep track of 
    discussion threads. </li>
  <li><font COLOR="#000000">You use the MAPI </font><tt><font FACE="Courier">Update</font></tt> 
    method to deliver discussion messages. You use the MAPI <tt><font FACE="Courier">Send</font></tt> 
    method to deliver mail messages. </li>
</ul>

<p>Now it's time to use Visual Basic to build the example forum tool. </p>

<h2><a NAME="TheDiscussProject"><b><font SIZE="5" COLOR="#FF0000">The Discuss Project</font></b></a></h2>

<p>For the rest of the chapter, you'll build a complete discussion tool that can be used 
to track ongoing messages in a target folder. You'll be able to use the program to read 
messages, generate replies to existing messages, and start new discussion threads. You'll 
also be able to select the target folder for the discussion. This way, you can use the 
same tool to monitor more than one discussion. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>The forum tool described in this chapter is a very basic project. Not much time will be 
      spent on the user interface. This is done to keep focus on the general issues of creating 
      a discussion tool for MAPI systems. If you plan to put a version of this project into 
      production, you'll want to add some bells and whistles to make this a more friendly 
      product.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>You'll use the OLE Messaging library (OML) to access MAPI services for this project. 
The OML gives you all the features you need to be able to manipulate message and folder 
properties within the MAPI file system. Although you can use the <tt><font FACE="Courier">MAPI.OCX</font></tt> 
to read most of the discussion-related properties, you cannot use the OCX to place 
messages in a target MAPI folder. Also, you cannot use the simple MAPI API declarations to 
gain access to target folders or to manipulate message properties. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Tip</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>If you are planning to build any software that manipulates folders, you'll need to use 
      the OLE Messaging library. No other Microsoft programming interface (besides the C MAPI 
      interface) allows you to gain access to the folders collection.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>There is one main code module and several forms in the Discuss project you'll build 
here. 

<ul>
  <li><i>MAPIPost</i>-This code module holds all the routines for posting new threads, 
    replying to threads, and collecting information on the available information stores, 
    folders, and messages available to the workstation. You can use the code here in other 
    Visual Basic discussion projects. </li>
  <li><i>modDiscuss</i>-This code module contains a few constants and global variables used 
    for the Discuss project. </li>
  <li><i>mdiDiscuss</i>-This is the main form. This acts as a wrapper for the note form and 
    the message list form. </li>
  <li><i>frmNote</i>-This form is used to read, compose, and reply to existing forum messages. 
  </li>
  <li><i>frmMsgs</i>-This form is used to display a list of discussion messages within the 
    target folder. The messages are shown in the threaded discussion form. </li>
  <li><i>frmOptions</i>-This form allows users to change the target folder for the discussion, 
    set the default MAPI logon profile, and control whether the message listing is shown in 
    threaded or flat-table format. </li>
  <li><i>frmAbout</i>-This is the standard About box for the project. </li>
</ul>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>Before you start coding the Discuss project, make sure you have added the OLE Messaging 
      type library. Do this by selecting <tt><font FACE="Courier">Tools </font></tt>|<tt><font
      FACE="Courier"> References</font></tt> from the main menu of Visual Basic. You will need 
      to install the OLE Messaging library from the MSDN CD-ROM before you can locate it using 
      the &quot;Tools | References&quot; menu option. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h2><b><a NAME="TheMAPIPostCodeLibrary"><font SIZE="5" COLOR="#FF0000">The </font><tt><font
SIZE="5" COLOR="#FF0000" FACE="Courier">MAPIPost</font></tt><font SIZE="5" COLOR="#FF0000"> 
Code Library</font></a></b></h2>

<p>The <tt><font FACE="Courier">MAPIPost</font></tt> Code Library contains several very 
important routines. These routines will be used throughout the project to gain access to 
folder collections and message collections within the folders. This also holds routines 
for posting new messages and generating replies to existing messages. There are also 
several routines for performing folder and message searches. You'll be able to use the 
routines in this module in other MAPI-related projects. </p>

<p>First, start a new Visual Basic project and add a BAS module (<tt><font FACE="Courier">Insert 
</font></tt>|<tt><font FACE="Courier"> Module</font></tt>). Set its <tt><font
FACE="Courier">Name</font></tt> property to <tt><font FACE="Courier">MAPIPost</font></tt> 
and save the file as <tt><font FACE="Courier">MAPIPOST.BAS</font></tt>. Now add the code 
shown in Listing 10.1 to the declaration section of the form. </p>

<hr>

<blockquote>
  <b><p>Listing 10.1. Adding the declarations for the module.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Option Explicit<br>
  <br>
  '<br>
  ' OLE message objects<br>
  Public objSession As Object<br>
  Public objMsgColl As Object<br>
  Public objMsg As Object<br>
  Public objRecipColl As Object<br>
  Public objRecip As Object<br>
  Public objAttachColl As Object<br>
  Public objAttach As Object<br>
  Public objAddrEntry As Object<br>
  Public objUserEntry As Object<br>
  Public objFolderColl As Object<br>
  Public objFolder As Object<br>
  Public objInfoStoreColl As Object<br>
  Public objInfoStore As Object<br>
  Public gnIndentlevel as Integer<br>
  Public cStoreID As String<br>
  <br>
  '<br>
  ' UDT for store/folder pairs<br>
  Type FolderType<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Name As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;FolderID As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;StoreID As String<br>
  End Type<br>
  '<br>
  Public FolderRec() As FolderType&nbsp;&nbsp;&nbsp;&nbsp;' members <br>
  Public iFldrCnt As Integer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  pointer<br>
  <br>
  '<br>
  ' UDT for message/conversation pairs<br>
  Type MsgType<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Subject As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Topic As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;ConvIndex As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MsgID As String<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Date As Date<br>
  End Type<br>
  '<br>
  Public MsgRec() As MsgType&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  members<br>
  Public iMsgCnt As Integer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  pointer<br>
  <br>
  '<br>
  ' type for creating Exchange-compliant timestamp<br>
  Type GUID<br>
  &nbsp;&nbsp;&nbsp;&nbsp;guid1 As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;guid2 As Long<br>
  Listing 10.1. continued<br>
  &nbsp;&nbsp;&nbsp;&nbsp;guid3 As Long<br>
  &nbsp;&nbsp;&nbsp;&nbsp;guid4 As Long<br>
  End Type<br>
  '<br>
  Declare Function CoCreateGuid Lib &quot;OLE32.DLL&quot; (pGuid As GUID) As Long<br>
  Public Const S_OK = 0</font></tt> </p>
</blockquote>

<hr>

<p>You'll notice the usual OLE Messaging library object declarations along with two 
user-defined types that will be used to keep track of message and folder collections. This 
will come in quite handy as you'll see later on. There is also the <tt><font
FACE="Courier">CoCreateGuid</font></tt> API call. You'll use this to generate unique <tt><font
FACE="Courier">ConversationIndex</font></tt> values for your message threads. </p>

<p>Next you need to add code that starts and ends MAPI services. Listing 10.2 shows the <tt><font
FACE="Courier">OLEMAPIStart</font></tt> and <tt><font FACE="Courier">OLEMAPIEnd</font></tt> 
routines. Add them to your project. </p>

<hr>

<blockquote>
  <b><p>Listing 10.2. Adding the <tt><font FACE="Courier">OLEMAPIStart</font></tt> and <tt><font
  FACE="Courier">OLEMAPIEnd</font></tt> routines.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Public Sub OLEMAPIStart(cUserProfile As String)<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;' start an OLE MAPI session<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;On Error Resume Next<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Set objSession = CreateObject(&quot;MAPI.Session&quot;) <br>
  &nbsp;&nbsp;&nbsp;&nbsp;objSession.Logon profilename:=cUserProfile <br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;If Err &lt;&gt; 0 Then<br>
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MsgBox &quot;Unable to Start MAPI 
  Services!&quot;, vbCritical, &quot;OLEMAPIStart&quot; <br>
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;End<br>
  &nbsp;&nbsp;&nbsp;&nbsp;End If<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub<br>
  <br>
  Public Sub OLEMAPIEnd()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;On Error Resume Next<br>
  &nbsp;&nbsp;&nbsp;&nbsp;objSession.Logoff ' end mapi session<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub</font></tt> </p>
</blockquote>

<hr>

<p>The next routines are used to build a collection of all the folders in all the message 
stores available to the workstation. You'll remember that MAPI 1.0 allows more than one 
message store for each workstation. Typically, users will have a personal message store, a 
server-based collection of messages, and possibly a message store related to an outside 
messaging service (such as Sprint, CompuServe, and so on). Each one of these stores has 
its own set of folders, too. The routine in Listing 10.3 shows you how you can enumerate 
all the folders in all the message stores and build a local user-defined type that you can 
use to locate and manipulate MAPI folders. Add the code shown in Listing 10.3 to your 
project. </p>

<hr>

<blockquote>
  <b><p>Listing 10.3. Adding the <tt><font FACE="Courier">CollectFolders</font></tt> 
  routine.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Public Sub CollectFolders(Optional ctrl As Variant)<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;' build folder tree<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Dim objRootFolder As Object<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Dim lobjFolders As Object<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Dim nIter As Integer<br>
  &nbsp;&nbsp;&nbsp;&nbsp;Dim nStoreCount as Integer<br>
  Dim bLoadCtrl As Boolean<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;' loading optional display?<br>
  &nbsp;&nbsp;&nbsp;&nbsp;If IsMissing(ctrl) Or IsNull(ctrl) Then <br>