How to Install Simple MAPI in Your VBApp Application

• Microsoft Visual Basic Programming System, Applications Edition, version 1.0
• Microsoft Excel for Windows, versions 5.0, 5.0c
• Microsoft Project for Windows, version 4.0

SUMMARY

This article contains information on how to implement Simple MAPI in your Visual Basic for Applications application. Note that this information is not needed for using MAPI in Visual Basic version 3.0. Users of Microsoft Visual Basic should use either the MSMAPI.VBX custom controls, or refer to the Microsoft Mail Technical Reference.

MORE INFORMATION

The Simple Messaging Application Programming Interface (MAPI) is a set of messaging functions that help you create messaging-enabled applications. It is a subset of MAPI, which provides complete access to messaging and information exchange systems.

With Simple MAPI, you can:

• Log on and off the messaging system.
• Find and read messages.
• Address new messages by adding recipients to the messages.
• Add attachments to messages.
• Save and send messages.

NOTE: For information on the C or Visual Basic implementations of Simple MAPI, please see the Microsoft Mail Technical Reference.

Requirements for Simple MAPI for Visual Basic for Applications

To use Simple MAPI for Visual Basic for Applications, you need:

• An application that includes Visual Basic for Applications, such as:

      - Microsoft Excel for Windows version 5.0 or later
      - Microsoft Project for Windows version 4.0 or later
      - Microsoft Windows for Workgroups version 3.1 or later
  

  -or-

• Microsoft Windows version 3.1 or later and Microsoft Mail for PC Networks version 3.0 or later.

NOTE: To use Simple MAPI with earlier versions of Microsoft Excel or Microsoft Project, use the Workgroup Extensions for Microsoft Excel or the Workgroup Extensions for Microsoft Project. These extension libraries are available in Microsoft Office Developer's Kit.

Components of Simple MAPI for Visual Basic for Applications

The Simple MAPI for Visual Basic for Applications library includes the following four files:

 VBAMAPI.DLL    Simple MAPI for Visual Basic for Applications run-time
                library

 VBAMAPI.TXT    Simple MAPI function and variable declarations

 VBAMAPI2.TXT   Additional function declarations for logon, logoff, and
                error checking

 MAPIVB.HLP     Documentation for Simple MAPI functions for Visual Basic
                and Visual Basic for Applications

 ~ VBAMAPI.EXE (size: 69050 bytes) 

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

Installing Simple MAPI for Visual Basic for Applications

To use Simple MAPI for Visual Basic for Applications, copy VBAMAPI.DLL to the Windows System directory (usually C:\WINDOWS\SYSTEM). All users require this file. VBAMAPI.DLL is a run-time library that you can freely copy to any system. Your users may require client, node, or end-user licenses for the messaging system you use.

Only developers require the other files. You can copy them to any directory.

Developing Applications with Simple MAPI for Visual Basic for Applications

To develop messaging applications with Simple MAPI for Visual Basic for Applications:

1. Include the Simple MAPI for Visual Basic for Applications declarations in your module.

2. Include correct logon and logoff functions in your module.

3. Refer to the Simple MAPI documentation for information about Simple MAPI data types and functions.

Including Simple MAPI Declarations

VBAMAPI.TXT includes the required declarations for Simple MAPI data types, functions and constants. You must include these declarations in your module to use Simple MAPI.

Microsoft Project version 4.0 already includes these declarations in the global file (GLOBAL.MPT). For Microsoft Excel version 5.0, you must add a module for the Simple MAPI declarations.

To add a module in Microsoft Excel:

1. Open a new or existing workbook.

2. From the Insert menu, choose Macro Module.

3. Move the insertion point to the end of the new module (after any Option statements), and choose File from the Insert menu.

4. In the Insert File dialog box, choose VBAMAPI.TXT.

Logging On and Off Mail Sessions

Microsoft Excel and Microsoft Project both include MailLogon and MailLogoff methods, so you should use these methods instead of the Simple MAPI MAPILogon and MAPILogoff functions.

In addition, Microsoft Excel and Microsoft Project provide a MailSession property that maintains the application's mail session, and the MailSystem property that identifies the current messaging system.

The file VBAMAPI2.TXT includes functions that use these built-in mail methods and properties. You can insert the example code listed in this section into your macro.

Logging On a Mail Session

You should add the following DoMailLogon function to your macro to log on a mail session. Because the MailLogon method logs off any existing session before logging on the new session, the function first checks to see whether a valid session already exists.

'********************************************************************
'DoMailLogon() uses the application's mail logon method
'rather than MAPILogon()
'********************************************************************

   ' Log on to Mail if not logged on already:
   If IsNull(Application.MailSession) Then
      Application.MailLogon
   End If
   ' Convert the hex string session handle to a long integer:
   DoMailLogon = CLng("&h" & Application.MailSession)

Logging Off a Mail Session

Add the following DoMailLogoff function to your macro to log off the mail session. This function only logs off if a valid mail session actually exists.

'********************************************************************
'DoMailLogoff uses the application's mail logoff method
'rather than MAPILogoff()
'********************************************************************
Sub DoMailLogoff()
   ' Logoff from Mail if logged on:
   If Not IsNull(Application.MailSession) Then
      Application.MailLogoff
   End If
End Sub

Simple MAPI Documentation

The MAPIVB.HLP file provides documentation for Simple MAPI for both Visual Basic and Visual Basic for Applications. This documentation is also available in the Microsoft Mail Technical Reference. You can refer to this documentation to see what MAPI functions you need to use in your own macros and how to call them.

How to Determine if MAPI Is Available

If you plan to distribute your macro to users of diverse messaging systems, your macro should determine if MAPI is available before using any Simple MAPI functions. In Microsoft Excel and Microsoft Project, the MailSystem property identifies the user's current messaging system.

How to Display Simple MAPI Errors

The file VBAMAPI2.TXT includes the GetMAPIErrorText function, which you can use to convert MAPI integer error codes to strings.

Alternatives to Simple MAPI

Not all applications need the full functionality of Simple MAPI. Microsoft Excel and Microsoft Project provide built-in messaging functionality that is easier to use for less complicated tasks. In Excel, you can use the SendMail method of the Workbook object and the RoutingSlip object to send files to users. In Microsoft Project, the MailSend and MailRoutingSlip methods of the Application object offer similar functionality.

Microsoft Excel and Microsoft Project have built-in messaging functionality that works with MAPI and with Vendor Independent Messaging (VIM) systems; while the Simple MAPI functions require a MAPI-compatible messaging system.

Finding Sample Code

Sample applications are available in Microsoft Office Developer's Kit.