CDO & MAPI Programming with Visual Basic:

The MAPISession Control

The MAPISession control is used for signing onto and off of the MAPI Subsystem. Your program must sign onto the MAPI Subsystem before it can work with messages. Signing on establishes a MAPI session; signing off releases the session.

During sign on, your program tells MAPI which profile to use during the session. MAPI accesses the profile to discover which mail services (message store, address book, and transport providers) to load. Again, refer to Chapter 2 for more information on profiles and service providers. Once signed on, you can use the MAPIMessages control to work with messages in the MAPI Inbox.

To sign on, set the MAPISession control’s UserName property to the name of the profile you want to use, then call the SignOn method, as shown here:

With MAPISession1
   .UserName = "MyProfile"
   .SignOn
End With

I’ve left the Password property blank because the profile itself specifies any username and password needed to authenticate to the underlying service providers. Older mail systems, such as Microsoft Mail, didn’t use profiles—they required the username and password to be set directly in the MAPISession control.

Given the MAPISession control’s default values, the previous code is equivalent to:

With MAPISession1
   .DownLoadMail = True
   .LogonUI = True
   .NewSession = False
   .Password = ""
   .UserName = "MyProfile"
   .SignOn
End With

It’s likely that you’ll want to adjust these property settings to achieve precisely the effects you’re looking for, so I’ll address each in turn.

The DownLoadMail property tells the MAPI subsystem to retrieve mail from the mail server during the sign-on process. This forces your modem to dial out if you’re using dialup networking. You may wish to set this property to False if you want to allow the user to manipulate messages in the Inbox while offline. After working offline, you can force a dial out to send messages from the Outbox and to receive new messages. This is done by logging out of the MAPI Subsystem (calling the SignOff method), then setting the DownLoadMail property to True, then logging back into the MAPI subsystem (calling the SignOn method). This is the only way to empty the Outbox programmatically of messages that were “sent” while offline. Note also that some service providers (e.g., Microsoft Exchange Server) allow you to specify a schedule for automatically downloading new mail from the mail server (and uploading sent mail). This is configured in the profile.

The DownLoadMail property’s name may be misleading. You might think it controls whether a copy of each message is left on the mail server. This isn’t the case. The service provider configuration in the profile determines whether retrieved messages are deleted from the mail server. To view a service provider’s property page, run the Mail applet in the Control Panel, highlight the service you’d like to view, and click Properties. For example, on the property page for Microsoft Exchange Server, you’ll find a checkbox labeled “Enable offline use.” (See Figure 4-3.) If this is checked, the Exchange service provider automatically deletes messages from the mail server after they’ve been copied to your local computer. Similarly, on the property page for the Internet E-mail service provider, you’ll find a checkbox labeled “Leave a copy of messages on server.” (See Figure 4-4.)

Figure 4-3. The Microsoft Exchange Server service provider property page, showing the “Enable offline use” checkbox

Figure 4-4. The Internet E-mail service provider property page, showing the “Leave a copy of messages on server” checkbox

The LogonUI property controls whether a dialog box is displayed to the user during sign-on in the event of a sign-on failure. If the profile name is properly specified in the UserName property and there is no problem signing on, no dialog box is displayed, regardless of the setting of this property. If there is some problem signing on—for example, if an invalid profile is specified—the LogonUI property is checked. If its value is True, the MAPI subsystem displays a dialog box presenting a list of valid profile names from which the user must choose. The user can either select from the list and continue, or choose Cancel. If the user chooses Cancel, a mapLoginFail error is raised in your code. (Note that "mapLoginFail" in the previous sentence isn’t a typo. This constant and others used by the MAPI ActiveX controls begin with "map“, not "mapi“.) If there was a problem signing on, and the LogonUI property contains False, in that case too a mapLoginFail error is raised in your code.

The NewSession property of the MAPISession control determines whether SignOn uses a new or existing MAPI session. If the property is set to True, a new MAPI session is created using the profile specified in the UserName property. If UserName is blank or invalid, either an error occurs (if LogonUI=False), or the user is prompted to select a valid profile (if LogonUI=True).

If the NewSession property is set to False, its default value, the MAPISession control attempts to locate an existing MAPI session on the machine. If found, it signs on using that session, regardless of the profile specified in the UserName property. If there is currently no MAPI session active on the machine, a new one is created using the profile specified in the UserName property.

Tip

The problem with signing on to an existing session is that you don’t know which profile is being used. Applications that need to use a specific profile should set the NewSession property to True. Applications that just want to attach to a profile already in use should set the NewSession property to False.

Your code should set the UserName property equal to the name of a MAPI profile set up on the user’s system, or leave it blank. If you leave it blank, the mail system prompts the user to select from the list of profiles set up on the system. If the UserName property contains a non-blank string that isn’t the name of a profile, MAPI displays an error message, then shows the list of valid profiles from which to choose. Be aware that the Choose Profile dialog box has a Cancel button, which, if pressed, raises a mapLoginFail error in your code. Be prepared to handle this error. Note also that the MAPI controls don’t provide a way to get a list of profiles programmatically. (However, see Chapter 2 for a way to read profile names from the system registry.)

When you’re finished using MAPI, sign off using the MAPISession control’s SignOff method:

MAPISession1.SignOff