Choose a specific version of MAPI to load
Applies to: Outlook 2013 | Outlook 2016
When linking explicitly to an implementation of MAPI, you must carefully select which implementation to load.
There are two methods to link explicitly to an implementation of MAPI.
You can load the MAPI stub library, and specify in the registry a custom DLL to load and dispatch MAPI calls to.
You can implement the MAPI client lookup algorithm to look up the version of MAPI used by the default mail client and load it.
Because you can change the Mapi32.dll Stub Registry Settings to direct your application to use any implementation of MAPI, we recommend that you direct your application to use an implementation of MAPI that you have tested with. The following describes both methods of linking explicitly.
Reading from the registry
To read MAPI implementation information from the registry
The registry keys that indicate a custom DLL for a mail client are located under the
HKLM\Software\Clients\Mailkey of the mail client.
The following table describes these keys:
Key Description MSIComponentID A Windows Installer PublishComponent category ID (GUID) that identifies the DLL that exports simple MAPI or MAPI calls. If set, this key takes precedence over the DLLPath or DLLPathEx key. MSIApplicationLCID Locale identifier (LCID) for your application. The first string value identifies a sub-key from
HKLM\Softwareand subsequent string values identify registry values underneath this key that contain locale information.
MSIOfficeLCID LCIDs for Microsoft Office. The first string value identifies a sub-key from
HKLM\Softwareand subsequent string values identify registry values underneath this key.
Obtain the information from these keys.
Pass the values that you obtained from the previous step to the FGetComponentPath function. FGetComponentPath is a function that is exported by the MAPI stub library Mapistub.dll. It returns the path of the custom version of MAPI.
To load the implementation of MAPI marked as default
Look up the information for the indicated client as described earlier.
Note that the default mail client might not implement Extended MAPI.
To load MAPI as implemented by Outlook, look up the registry keys under
HKLM\Software\Clients\Mail\Microsoft Outlook and pass them to FGetComponentPath. FGetComponentPath will return the path for Outlook's implementation of MAPI.
If the keys MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID are not set, check the DLLPathEx registry value. If the keys are set, FGetComponentPath gives the path of the client's implementation of MAPI.
Implementing the MAPI Client Lookup algorithm
The following table lists the four functions from MFCMAPI that are used to look up the path for a custom implementation of MAPI:
||Gets the MAPI library path.
||Gets the MAPI mail registry key.
||Gets the Windows Installer identifier.
||Gets the component path using FGetComponentPath.
Because MFCMAPI loads the default implementation of MAPI by default, if you want to use a different implementation of MAPI, you must explicitly direct it to do so. This is performed by using the Session\Load MAPI routine.
How these functions work
GetMAPIPath, passing NULL for the client parameter, to load the default MAPI implementation.
GetMapiMsiIdsto read the values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID.
GetMailKeyto open the registry key for the default mail client.
GetMapiMsiIdsuses the registry handle returned by
GetMailKeyto look up values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID.
The values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID, are returned to
GetMAPIPaththen passes them to
GetComponentPathloads the MAPI stub library, Mapi32.dll, from the system directory.
GetComponentPaththen retrieves the address of the FGetComponentPath function from Mapi32.dll, assuming that Mapi32.dll exports FGetComponentPath.
If getting the address of FGetComponentPath from Mapi32.dll fails,
GetComponentPathretrieves the address from Mapistub.dll.
GetComponentPaththen calls FGetComponentPath, obtaining the path of the default version of MAPI.
GetMAPIPaththen returns this path to the caller, which then loads MAPI and explicitly links to it as described in Link to MAPI Functions.
- To support localized copies of MAPI for English and non-English locales,
GetMAPIPathreads the values for the MSIApplicationLCID and MSIOfficeLCID subkeys.
GetMAPIPaththen calls FGetComponentPath, first specifying MSIApplicationLCID as szQualifier, and again specifying MSIOfficeLCID as szQualifier. For more information about registry keys for mail clients that support non-English languages, see Setting Up the MSI Keys for Your MAPI DLL.
- If MFCMAPI does not receive a path for MAPI using
GetMAPIPath, it loads the MAPI stub library from the system directory.
- The MSMapiApps registry value discussed in Explicitly Mapping MAPI Calls to MAPI DLLs only applies when the MAPI Stub library is used. Applications that load a specific implementation of MAPI or load the default implementation do not have to set the MSMapiApps registry key.