Platform SDK: MAPI

Mapi32.dll Stub Registry Settings

The stub library uses values under the default mail key to dispatch simple and extended MAPI calls. The default mail client for simple or extended MAPI calls is defined by the HKLM\Software\Clients\Mail::(default) registry value. This value identifies a subkey that contains information about the current default mail client. For example:

Mail::(Default) [="Microsoft Outlook"]
     \Microsoft Outlook::DLLPath  [="MAPI32.dll"]
     \Microsoft Outlook::MSIComponentID [="{GUID}"]
     \Microsoft Outlook::MSIApplicationLCID [=value]
     \Microsoft Outlook::MSIOfficeLCID [=value]
     \Outlook Express::DLLPath   [="c:\%SYSTEMDRIVE%\Program Files\Microsoft Outlook\msoe.dll."]
....

The registry values used under a particular mail client key are listed in the following table:

Reg Key Type Description
DLLPath REG_SZ Full path to the simple MAPI provider DLL.
DLLPathEx REG_SZ Full path to the extended MAPI provider DLL. Provider DLLs that support both simple and extended MAPI must have both keys set.
MSIComponentID REG_DWORD A Microsoft Software installer PublishComponent category id that in turn identifies the DLL that exports simple or extended MAPI calls. If set, this key takes precedence over DLLPath or DLLPathEx. For more information on configuring the installer, see Setting Up the MSI Keys for Your MAPI DLL.

Depending on the type of MAPI call received, the stub library loads the appropriate DLL as defined by the registry keys and values for the default mail client and then dispatches the call. Simple MAPI calls are dispatched to the DLL pointed to by DLLPath, and extended MAPI calls are dispatched to the DLL pointed to by DLLPathEx. However, if the MSIComponentID registry key is listed under the mail client key, the stub library installs the component on demand using the MSI, loads the DLL, and dispatches the calls.

If there is no default mail client or if none of the DLLs identified by the default mail client support the requested MAPI functionality, the stub library checks for the existence of Mapi32x.dll and Mapisvc.inf (indicating the presence of a MAPI mail client) in the system directory. If they are found, the stub library loads Mapi32x.dll and dispatches the call. This mechanism allows for the Microsoft Exchange client and earlier versions of Outlook to continue using the original (renamed to Mapi32x.dll) Mapi32.dll.

If the DLLs defined in the default mail client key cannot handle a MAPI call and if Mapi32x.dll and Mapisvc.inf files do not exist in the system directory, the stub library displays a first-time initialization message by using the strings in the PreFirstRun value of the HKLM\Software\Clients\Mail key. The format of the string is "<messagebox text>* <messagebox caption>". This string allows applications to present a message if they need to prepare for handling particular MAPI calls upon first request. The stub library subsequently returns E_FAIL to all MAPI calls that cannot be handled by the default mail client configuration after the initial message is displayed.