ch7.htm

MAPI__SAPI__TAPI

<p>You can use the <tt><font FACE="Courier">NewSession</font></tt> property to force the 
creation of a new MAPI session, even if a MAPI session already exists for this 
workstation. By default, the <tt><font FACE="Courier">SignOn</font></tt> method will 
attempt to locate any current MAPI interface sessions before attempting to log on to the 
mail server. When you set the <tt><font FACE="Courier">NewSession</font></tt> parameter to 
<tt><font FACE="Courier">True</font></tt>, the <tt><font FACE="Courier">SignOn</font></tt> 
method will create a second MAPI session link with the mail server. The code in Listing 
7.3 shows how this is done. </p>

<hr>

<blockquote>
  <b><p>Listing 7.3. Setting the <tt><font FACE="Courier">NewSession</font></tt> property of 
  the <tt><font FACE="Courier">MAPISession</font></tt> control.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Private Sub Form_Load()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  MAPISession1.DownloadMail = False&nbsp;&nbsp;&nbsp;' dont get new mail<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.NewSession = True&nbsp;&nbsp;' force a new session<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOn<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOff<br>
  &nbsp;&nbsp;&nbsp;&nbsp;End<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub</font></tt> </p>
</blockquote>

<hr>

<p>The <tt><font FACE="Courier">Password</font></tt> and <tt><font FACE="Courier">UserName</font></tt> 
properties should be set to valid values if you want to bypass the default logon screen. 
If you supply a <tt><font FACE="Courier">UserName</font></tt> but leave the <tt><font
FACE="Courier">Password</font></tt> property blank, the <tt><font FACE="Courier">SignOn</font></tt> 
method will force the logon dialog box to appear and prompt for the missing information. 
If, however, the <tt><font FACE="Courier">LogonUI</font></tt> property is set to <tt><font
FACE="Courier">False</font></tt>, no dialog box will appear, and an error will be 
returned. </p>

<p>If you are using the Microsoft Exchange Mail Client, you only need to provide a valid 
Profile Name. Microsoft Exchange Mail will ignore any value in the <tt><font
FACE="Courier">Password</font></tt> property. If you are using the Microsoft Mail client 
(network or workgroup version), you will need to supply both the <tt><font FACE="Courier">UserName</font></tt> 
and the <tt><font FACE="Courier">Password</font></tt> properties if you want to bypass the 
default logon dialog box. Refer to Listing 7.4 for an example. </p>

<hr>

<blockquote>
  <b><p>Listing 7.4. Getting the username and password at sign-on. <br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Private Sub Form_Load()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.DownloadMail = False&nbsp;&nbsp;&nbsp;' don't get new 
  mail<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.NewSession = True&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  force a new session<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.UserName = &quot;MCA&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  username for mail<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.Password = &quot;PASSWORD&quot;&nbsp;&nbsp;' users 
  password<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOn<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOff<br>
  &nbsp;&nbsp;&nbsp;&nbsp;End<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub</font></tt> </p>
</blockquote>

<hr>

<p>The <tt><font FACE="Courier">SessionID</font></tt> property is a read-only property 
available only at run-time that contains the unique session ID number of a completed link 
between your Visual Basic program and the mail server. This session ID value must be used 
in all transactions to the mail server. Its value is used to set the <tt><font
FACE="Courier">SessionID</font></tt> of the <tt><font FACE="Courier">MAPIMessage</font></tt> 
control before attempting to access the message services provided by the mail server. The 
code in Listing 7.5 displays the value of the <tt><font FACE="Courier">SessionID</font></tt> 
after a successful logon of the user. </p>

<hr>

<blockquote>
  <b><p>Listing 7.5. Displaying the <tt><font FACE="Courier">SessionID</font></tt> property.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Private Sub Form_Load()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.DownloadMail = False&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  dont get new mail<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.NewSession = True&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  force a new session<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.UserName = &quot;VBU Profile&quot;&nbsp;' username 
  for mail<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.Password = &quot;&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' 
  user password<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOn<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MsgBox Str(MAPISession1.SessionID)&nbsp;&nbsp;&nbsp;&nbsp;' show 
  unique session handle<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOff<br>
  &nbsp;&nbsp;&nbsp;&nbsp;End<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub</font></tt> </p>
</blockquote>

<hr>

<p>Modify the <tt><font FACE="Courier">UserName</font></tt> and, if needed, the <tt><font
FACE="Courier">Password</font></tt> properties to contain valid logon data for your mail 
server. Then save and run the project. You will see a message box that shows the unique 
session handle for the MAPI session (see Figure 7.3). </p>

<p><a HREF="f7-3.gif"><b>Figure 7.3 : </b><i>Displaying the SessionID of a MAPI session.</i></a> 
</p>

<h3><a NAME="TheMAPIMessageControl">The <tt><font SIZE="4" FACE="Courier">MAPIMessage</font></tt><font
SIZE="4"> Control</font></a></h3>

<p>The <tt><font FACE="Courier">MAPIMessage</font></tt> control gives your Visual Basic 
program access to all the message services available from the mail server with which your 
program has established a session. The <tt><font FACE="Courier">MAPIMessage</font></tt> 
control provides services for reading, composing, addressing, and sending mail messages. 
You can perform all major mail operations by requesting the service from the server. </p>

<p>The <tt><font FACE="Courier">MAPIMessage</font></tt> control has four primary 
functions: 

<ul>
  <li><font COLOR="#000000">Creating and sending messages</font> </li>
  <li><font COLOR="#000000">Reading any new messages</font> </li>
  <li><font COLOR="#000000">Deleting any old messages</font> </li>
  <li><font COLOR="#000000">Maintaining the address list</font> </li>
</ul>

<p>There are 11 methods and over 30 properties of the <tt><font FACE="Courier">MAPIMessage</font></tt> 
control that are MAPI-related. We'll review these methods and properties briefly. You can 
find additional documentation on each of the <tt><font FACE="Courier">MAPIMessage</font></tt> 
properties in the Visual Basic online help files. </p>

<h4>Methods</h4>

<p>There are 11 methods for the <tt><font FACE="Courier">MAPIMessage</font></tt> control: 

<ul>
  <li><font COLOR="#000000">To create and send messages, the control uses the </font><tt><font
    FACE="Courier">Compose</font></tt>, <tt><font FACE="Courier">Copy</font></tt>, <tt><font
    FACE="Courier">Forward</font></tt>, <tt><font FACE="Courier">Reply</font></tt>, <tt><font
    FACE="Courier">ReplyAll</font></tt>, and <tt><font FACE="Courier">Send</font></tt> 
    methods. </li>
  <li><font COLOR="#000000">To read messages, the control uses the </font><tt><font
    FACE="Courier">Fetch</font></tt> method. </li>
  <li><font COLOR="#000000">To manage old messages, the control uses the </font><tt><font
    FACE="Courier">Save</font></tt> and <tt><font FACE="Courier">Delete</font></tt> methods. </li>
  <li><font COLOR="#000000">To maintain the address list, the control uses the </font><tt><font
    FACE="Courier">Show</font></tt> and <tt><font FACE="Courier">ResolveName</font></tt> 
    methods. </li>
</ul>

<p>The message-creation methods account for six of the eleven methods. Of these six, you 
only need to know two before you can create a functional e-mail application. The <tt><font
FACE="Courier">Compose</font></tt> method clears out the edit buffer area and prepares a 
clean slate for the creation of a new message. The <tt><font FACE="Courier">Send</font></tt> 
method attempts to send the new message to the address supplied. If an address or message 
is not supplied, the <tt><font FACE="Courier">Send</font></tt> method forces the mail 
server to present the default message compose form to the user. </p>

<p>In other words, you can create a complete e-mail composer by adding only two lines to 
the code we started earlier in this chapter. The code shown in the following listing is 
all you need to create a Visual Basic application that can compose and send e-mail 
messages. Start a new Visual Basic project and add the <tt><font FACE="Courier">MAPISession</font></tt> 
and the <tt><font FACE="Courier">MAPIMessage</font></tt> controls to the form. Then add 
the code shown in Listing 7.6 to the <tt><font FACE="Courier">Form_Load</font></tt> event. 
</p>

<hr>

<blockquote>
  <b><p>Listing 7.6. Creating a <tt><font FACE="Courier">MAPIMessage</font></tt>. <br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Private Sub Form_Load()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOn&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' log into MAPI 
  server<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPIMessages1.SessionID = MAPISession1.SessionID <br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPIMessages1.Compose&nbsp;&nbsp;&nbsp;' clear buffers<br>
  Listing 7.6. continued<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPIMessages1.Send True ' show default form<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOff&nbsp;&nbsp;&nbsp;&nbsp;' exit MAPI server<br>
  &nbsp;&nbsp;&nbsp;&nbsp;End<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  End Sub</font></tt> </p>
</blockquote>

<hr>

<p>Now save the form as <tt><font FACE="Courier">CDG0702.FRM</font></tt> and the project 
as <tt><font FACE="Courier">CDG0702.VBP</font></tt>, and run the program. You'll be 
prompted for a logon, and then you'll see the default compose form. Figure 7.4 shows what 
comes up if you are using Microsoft Exchange Mail. </p>

<p><a HREF="f7-4.gif"><b>Figure 7.4 : </b><i>The default compose form for Microsoft 
Exchange.</i></a> </p>

<p>Notice that you have a highly functional e-mail program with very little coding. Use 
this form to send yourself a message. We'll use other Visual Basic code to read the 
message later in this chapter. </p>

<p>You can use the other message creation methods (<tt><font FACE="Courier">Copy</font></tt>, 
<tt><font FACE="Courier">Forward</font></tt>, <tt><font FACE="Courier">Reply</font></tt>, 
and <tt><font FACE="Courier">ReplyAll</font></tt>) to load the compose buffer with 
messages that have been sent to you by others. You can then use the default compose dialog 
box to edit the old message and send it just as you would a new message you created from 
scratch. The <tt><font FACE="Courier">Forward</font></tt>, <tt><font FACE="Courier">Reply</font></tt>, 
and <tt><font FACE="Courier">ReplyAll</font></tt> methods also alter the subject line to 
reflect the action. For example, when you use the <tt><font FACE="Courier">Forward</font></tt> 
method, the mail server will add &quot;FW:&quot; to the beginning of the subject line. The 
<tt><font FACE="Courier">Reply</font></tt> methods place &quot;RE:&quot; at the start of 
the subject line. </p>

<p>The code example in Listing 7.7 takes the first message in the user's inbox and copies 
it to the compose buffer with &quot;FW:&quot; on the subject line. </p>

<hr>

<blockquote>
  <b><p>Listing 7.7. Forwarding a message.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Private Sub Form_Load()<br>
  &nbsp;&nbsp;&nbsp;&nbsp;'<br>
  &nbsp;&nbsp;&nbsp;&nbsp;MAPISession1.SignOn&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;' log into MAPI 
  server<br>