PRB: Simple MAPI BMAPI Functions May Not Work from Visual Basic Code

Calls to the MAPISendMail function that are made from Microsoft Visual Basic code may fail with an error message that resembles the following: This problem often occurs when Microsoft Outlook Express is set as the default mail client.

Visual Basic programs that use Simple MAPI typically use Declare statements that import the BMAPI functions. When Outlook Express is the default mail client, the MAPI stub library cannot route these calls to Outlook Express; instead, the calls fail and an error message is displayed.

One way to resolve this problem is to not use Declare statements that reference the BMAPI functions. However, because Visual Basic cannot call the non-BMAPI functions (unless you manipulate the required structures at the binary level), you may want to write code to call the Simple MAPI functions from a language that can handle the structures, such a C or C++.

Two other resolutions are provided at the end of the "More Information" section.

This behavior is by design.

The MAPI stub library, Mapi32.dll, is the DLL that is typically loaded by a client application to use Simple MAPI. The stub library routes calls to the appropriate MAPI implementation, based on registry settings. In this way, various implementations can coexist without overwriting each other.

When a call is made to a function exported by the stub library, the library follows these steps:

1. It determines whether the function is a Simple MAPI function or an Extended MAPI function. The following export functions are marked in the stub library as being Simple MAPI functions:
   
   
   • MAPIAddress
   • MAPIDeleteMail
   • MAPIDetails
   • MAPIFindNext
   • MAPIFreeBuffer
   • MAPILogoff
   • MAPILogon
   • MAPIReadMail
   • MAPIResolveName
   • MAPISaveMail
   • MAPISendDocuments
   • MAPISendMail
   
   All other export functions are Extended MAPI functions.
2. It looks in the following registry key to determine the current default MAPI implementation:
   HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Mail::(default)
3. It then looks under the client's key to find the path of the correct DLL to load. If the function is a Simple MAPI function, it loads the DLL specified by the DllPath value, and then calls the function. If the function is an Extended MAPI function, it loads the DLL specified by the DllPathEx value. After finding the appropriate DLL, it then calls the function.
   
   In the case of Microsoft Outlook, for example, it looks for the value of DLLPath or DLLPathEx under the following key:
   HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Mail\Microsoft Outlook
4. If DllPathEx or DllPath is not found, the stub library uses the Mapi32x.dll file, which is located in the same directory as the stub library. This file is typically a renamed copy of the Mapi32.dll file that already existed when the stub library was installed. On many systems, especially those where only Outlook and Outlook Express have been installed, this file does not exist.
5. If the stub library fails to find Mapi32x.dll, it displays the message that is located in one of the following keys:
   HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Mail::PreFirstRun
   
   -or-
   
   HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Mail::NoMailClient

The reason for the problem when using Outlook Express is as follows:

1. Most Visual Basic code uses Declare statements based on the Mapivb32.bas module, which imports MAPISendMail as BMAPISendMail. Most of the other SimpleMAPI functions are also declared with their BMAPI equivalents.For additional information, click the article number below to view the article in the Microsoft Knowledge Base:
   163216  (http://support.microsoft.com/kb/163216/EN-US/ ) Updated Mapivb32.bas for Simple MAPI on 32-Bit Platforms
2. Because the BMAPI functions are not on the list of Simple MAPI functions which use the DLL specified in DllPath, the stub library routes them by using the value in DllPathEx.
3. Because Outlook Express does not implement Extended MAPI, it has no value set for DllPathEx.
4. The stub library attempts to use Mapi32x.dll, which does not exist, and as a result displays the PreFirstRun message.

There are two additional ways to work around the problem:

• A temporary resolution is to determine whether Outlook Express is the default mail client, and if it is, add a DllPathEx value to the registry as follows:
  HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Mail\Outlook Express::DllPathEx = %ProgramFiles%\Outlook Express\msoe.dll
  WARNING: If you use Registry Editor incorrectly, you may cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that you can solve problems that result from using Registry Editor incorrectly. Use Registry Editor at your own risk.
  
  Because Outlook Express implements and exports the BMAPIFunctions from Msoe.dll, setting DllPathEx allows the stub library to route calls to them. The danger in doing this is that a client that attempts to use Extended MAPI will receive an error (because Msoe.dll does not export the Extended MAPI functions) when it might instead have used Mapi32x.dll successfully.
• To force an application to use the Outlook Express implementation for all MAPI calls, create a new value under the following registry key:
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Messaging Subsystem\MSMapiApps
  Set the name of the value to the name of your application (such as MyApp.exe), and then set the value to Outlook Express. This bypasses the stub library and forces it to pass all MAPI calls, including the BMAPI calls, directly to Outlook Express.