Using the MAPI Controls

See Also

The messaging application program interface (MAPI) controls allow you to create mail-enabled Visual Basic applications. MAPI is a set of core system components that seamlessly connect any mail-enabled or workgroup application to MAPI-compliant information services. For example, the Microsoft Exchange messaging system can be connected to most private or public e-mail systems through the use of MAPI drivers.

In Visual Basic, the MAPI controls are used to interact with the underlying message subsystem. To use these controls, you must first install a MAPI-compliant e-mail system like Microsoft Exchange. The underlying messaging services are provided by the workgroup environment — the Microsoft Exchange Server running under Windows 95 or Windows NT, for instance.

Using the MAPI controls involves two steps: establishing a MAPI session and then using various properties and methods to access and manage an individual Inbox. For example, create and send a message, include a file attachment, verify the recipient's address against the e-mail system's address book, etc.

The MAPISession control signs on and establishes a MAPI session. It is also used to sign off from a MAPI session. The MAPIMessages control contains all the properties and methods needed to perform the messaging system functions described above.

The MAPI controls are invisible at run time. In addition, there are no events for the controls. To use them you must set the appropriate properties or specify the appropriate methods.

Note   If you attempt to run a program that uses the MAPI controls, make sure that you have the 32-bit MAPI DLLs installed properly or you may not be able to perform MAPI functions such as SignOn. For example, on Windows 95, you must install Exchange during the operating system setup, or install it separately from the control panel to correctly use MAPI functions.

Possible Uses

• To add messaging functionality to your application.
  
  
• To create a full-featured electronic mail application.

Using the MAPISession control

The MAPISession control is used to sign in and out of a MAPI session. Assuming that MAPI services are present, logging in with the MAPISession control is merely a matter of providing a registered user name and password. The MAPISession control will determine the electronic mail settings specified in the operating system and invoke the underlying message subsystem (the mail server).

The MAPISession control

Setting MAPISession Properties

You can set the MAPISession properties at design time using the MAPISession Property Pages. Right-click the MAPISession control and click Properties to display the Property Pages dialog box.

Setting the MAPISession properties at design time

The UserName and Password properties are used to provide a valid sign-on to the underlying messaging system. You can either set these properties at design time or prompt the user at run time. Setting the LogonUI property to True will provide the user with the sign-on dialog box of the underlying mail system. If such a dialog box does not exist, this property will be ignored. You can create a custom dialog box to prompt the user for this information.

The NewSession property specifies whether a new mail session should be established. If a valid session is already established, setting the NewSession property will allow two sessions to run concurrently.

The DownloadMail property specifies whether the user's mail will be downloaded at the beginning of the current session automatically. Setting this value to True will download all the user's mail to their Inbox. Depending upon the mail system and the amount of incoming mail, this can be a processing-intensive operation. By setting this property to False, the user can choose to download mail at a later time or set the interval at which mail is automatically downloaded.

The SignOn and SignOff Methods

Once the UserName and Password properties have been set, use the SignOn method at run time to begin the MAPI session.

For example:

mpsSession.SignOn

When the session is established, the session handle is stored in the SessionID property. Depending upon the value of the NewSession property, the session handle may refer to a newly created session or an existing session.

To end the session use the SignOff method.

Note   The Action property can also be used to sign in and out of a MAPI session. It is recommended, however, that you use the SignOn and SignOff methods instead. The Action property is included for compatibility with earlier versions of Visual Basic.

The SessionID Property

When the SignOn method is used to successfully establish a messaging session, the SessionID property will return a unique messaging session handle. The SessionID value will be used by the MAPIMessages control to create an association with a valid messaging session. By default, this value is 0.

Using the MAPIMessages Control

Once you've logged into a messaging session using the MAPISession control, you use the MAPIMessages control to receive, send, or read messages from the Inbox which was specified at sign-on time.

The MAPIMessages control provides you with properties and methods to perform basic electronic mail tasks. For example, composing a message, addressing it to a recipient, verifying that the recipient's address is valid, or attaching a file.

The MAPIMessages control

In most cases, the MAPIMessage control is used to provide e-mail capabilities to certain functions within an application. For example, you may want to send a notification message to a workgroup alias after your application has automatically created a report. In other words, you can add e-mail capabilities to your application, without creating full-fledged e-mail applications.

You can, however, use the MAPI controls to create very powerful mail-enabled and workgroup applications.

Sample Application: VBMail.vbp

The examples in the following sections demonstrate the basic use of MAPI in Visual Basic. For more detailed use of the properties and methods of the MAPI controls refer to the VBMail.vbp sample application, which is listed in the Samples directory.

Note   You can also use the OLE Messaging technology to add MAPI functionality to your application. Information on OLE Messaging can be found in the Microsoft Exchange Software Development Kit.

Associating SessionID Properties

The SessionID property of the MAPIMessages control contains the messaging session handle returned by the SessionID property of the MAPISession control. To associate the MAPIMessages control with a valid messaging session, set this property to the SessionID of a MAPISession control that was successfully signed on. For example:

mpmMessage.SessionID = mpsSession.SessionID

This association to a valid MAPI session must be made before you can access messages and begin working with the MAPIMessages control.

Accessing Messages

Successfully logging into a MAPI session accesses the Inbox of the registered user specified by the UserName and Password properties of the MAPISession control. The Inbox is the message store. When the Inbox is opened two buffers are created: the compose buffer and the read buffer.

The read buffer is made up of an indexed set of messages fetched from the user's Inbox. The MsgIndex property is used to access individual messages within this set, starting with a value of 0 for the first message and incrementing by one for each message through the end of the set.

The message set is built using the Fetch method. The set includes all messages of type FetchMsgType and is sorted as specified by the FetchSorted property. The value of the FetchMsgType property is controlled by the underlying message system. The FetchSorted property can be set to add messages to the message set (read buffer) in the order they are received or in the order specified by the user's Inbox. Previously read messages can be included or left out of the message set with the FetchUnreadOnly property.

Messages in the read buffer can't be altered by the user, but can be copied to the compose buffer for alteration.

Messages are created or edited in the compose buffer. The compose buffer is active when the MsgIndex property is set to –1. Many of the messaging actions are valid only within the compose buffer, such as sending messages, saving messages, or deleting recipients and attachments.

Composing and Managing Messages

Managing messages is the primary function of the MAPIMessages control. Composing, sending, receiving, and deleting messages are performed by using methods that correspond to these basic functions (compose, copy, delete, etc.). The following table lists the MAPIMessages methods that specifically apply to messages:

To perform an action on an individual message, it must first be selected using the MsgIndex property. The message identified by the MsgIndex property is called the currently indexed message.

None of the other message properties can be set until a message is selected with the MsgIndex property. The index number can range from –1 to MsgCount –1 (the MsgCount property returns the total number of messages in the message set.) When a new message is created, the value of the MsgIndex property is set to –1.

Composing a Message

Use the Compose method to create a new message. When the Compose method is used, the compose buffer is cleared and the MsgIndex property is set to –1.

'Compose new message
mpmMessage.Compose

Completing a message involves several steps: determining the recipient of the message, choosing a subject title, and writing the message.

Addressing the Message

To set the recipient's name and address, use the RecipDisplayName and the RecipAddress properties. The RecipDisplayName is the proper name of the recipient, for example, "Richard Tull". The RecipAddress property contains the recipient's e-mail address: "richtull", for example.

'Address message
mpmMessage.RecipDisplayName = "Richard Tull"
mpmMessage.RecipAddress = "richtull"

Addresses for recipients outside the local workgroup (a message sent to someone at another company via the Internet, for example) require a complete Internet e-mail address: "richtull@littlemag.com".

Verifying the Recipient's Name

The recipient's name is verified when the message is sent by checking it against the list of registered users in the e-mail system, using the ResolveName method. Name verification for recipients outside the local workgroup is handled in various ways by the underlying message system.

The following example resolves the recipient's valid e-mail name by invoking the ResolveName method and setting the AddressResolveUI property to True.

' Resolve recipient name
mpmMessage.AddressResolveUI = True
mpmMessage.ResolveName

The AddressResolveUI property can be set to either display a details dialog box (True) or generate an error (False) when an ambiguous or invalid recipient address is encountered when the message is sent. The details dialog box will offer you an alternative address if a close match is found.

The Message Subject and Text

The MsgSubject property specifies the subject line for the message. You may enter up to 64 characters, including the Null character.

The body of the message is contained in the MsgNoteText property. For inbound messages, each paragraph is terminated with a carriage return-line feed pair (vbCrLf). Outbound messages can be delimited with a carriage return (vbCr), line feed (vbLf), or a carriage return-line feed pair.

'Create the message
mpmMessage.MsgSubject = "Status Report"
mpmMessage.MsgNoteText = "Build successful!"

Sending the Message

To send the message, use the Send Method. The Send method allows you to send a message with or without user interaction. Setting the value to True will display the compose message dialog box of the underlying e-mail system (Microsoft Exchange, for example). Setting it to False will send the message without displaying the compose message dialog. The following example sends the message without prompting for user interaction:

'Send the message
mpmMessage.Send False

Handling File Attachments

You can add file attachments to outgoing messages using the file attachment properties. These properties are listed in the following table:

To add an attachment to an outgoing message, use the AttachmentPathName property to specify the name and path of the file. For example:

'Add attachment
mpmMessage.AttachmentPathName = "c:\Status _ 
Report.doc"

If the path name is incorrect or empty, an error will be generated.

Simply specifying the AttachmentPathName property will send the attachment with the message, use the name of the file to display in the message body, and position the attachment at the beginning of the message.

The AttachmentName property can be used to specify a different name for the attached file. If this property isn't set, the actual name of the file will be displayed in the message body.

The AttachmentPosition property is used to position the attachment within the message body. By default, the value is "0" and the attachment is located at the beginning of the message body. To position the attachment at the end of the message, count the number of characters in the message body. For example, in a message body that is five characters long, you could place an attachment at the end of the message by setting the value to 4. (The message body occupies character positions 0 to 4).

Two attachments can't be placed in the same position within the same message. You also can't place an attachment equal to or beyond the end of the message body. You can append an extra space or a vbCrLf character to the end of the message body and then set the AttachmentPosition property to one character less than the length of the MsgNoteText property.

Managing Messages

Many of the remaining properties and methods of the MAPIMessages control can be used to manage messages just as you would in a full-featured e-mail application.

By accessing messages in the read buffer you can sort, delete, or forward one or a number of messages. The following table lists the properties you can use to manage messages:

Working with the Address Book

The e-mail system's address book contains all of the addressing information for each registered user in the e-mail system. The address book is a dialog box which allows the user to look up or verify recipient addresses. The address book properties allow you to set or modify elements of the address book.

The Show Method

The e-mail system's address book is displayed using the Show method. The Show method can be set to show either the address book or the recipient details dialog box.

By default, the value is set to False and the address book dialog box is displayed when the Show method is used.

To display the details dialog box, set the value to True. The amount of information displayed in this dialog box depends upon the e-mail system. At minimum, the name and address of the recipient are displayed.

Address Book Properties

The address book properties allow you to set or modify elements of the e-mail system's address book. The following table lists these properties:

All of the address book properties can be set at design time using the MAPIMessages control's Property Pages dialog box.

Setting the MAPIMessages properties at design time

Setting the address book properties at design time allows you to specify options for the display and functionality of the address book dialog box. For example, you can modify the caption that appears in the address book dialog box using the AddressCaption property.