Microsoft KB Archive/121424

{|
 * width="100%"|

VB1: How to Install Simple MAPI in Your VBApp Application

 * }

Q121424

-

The information in this article applies to:


 * Microsoft Visual Basic Standard Edition for Windows, 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.

Simple MAPI functions are available for Microsoft C languages and Microsoft Visual Basic. This article discusses extensions to the Visual Basic implementation to support Visual Basic for Applications. The Simple MAPI function names, parameters, and return values are identical for both Visual Basic and Visual Basic for Applications.

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:


 * 1) An application that includes Visual Basic for Applications, such as:


 * 1) * Microsoft Excel for Windows version 5.0 or later
 * 2) * Microsoft Project for Windows version 4.0 or later
 * 3) * Microsoft Windows for Workgroups version 3.1 or later
 * 4) Microsoft Windows version 3.1 or later and Microsoft Mail for PC Networks version 3.0 or later.

You can use the Mail client application from Microsoft Windows for Workgroups with the Microsoft Windows for Workgroups post office, the Microsoft Mail for PC Networks post office, Microsoft Mail Remote, or with a variety of MAPI-compatible messaging service providers.

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 The following file is available for download from the Microsoft Download Center:

"Vbamapi.exe" For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

"Q119591 How to Obtain Microsoft Support Files from Online Services" Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

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 '******************************************************************** Function DoMailLogon As Long ' 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) End Function

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.

Additional query words: softlib

Keywords : kbfile kbinterop kbprogramming _IK

Issue type :

Technology : kbVBSearch kbExcelSearch kbAudDeveloper kbExcel500 kbProjectSearch kbExcel500c kbProject400