We just released the April 2005 update to the Outlook 2003 Integration API.
Download for the CHM is here:
http://www.microsoft.com/downloads/details.aspx?FamilyId=135F4D99-F480-4A81-AF8F-F6E4896611E2
The MSDN documentation should update some time in the next few days. When it does, you'll find it here:
http://msdn.microsoft.com/en-us/library/aa193231.aspx
Note that the date on the Welcome page will be updated from December 2004 to April 2005 when the updates go live.
Many thanks to Dmitry for some valuable feedback that went in to this update.
As always, let me know any questions/concerns you have with the documentation.
There is an article which you used to be able to find at http://support.microsoft.com/kb/259301. This article, which I helped to write, walked you through the mechanics of impersonating a user before using MAPI. I pulled this article recently and just wanted to discuss briefly why.
There are three main problems with doing impersonation and then using MAPI: registry access, support threads, and instance data.
The first problem is that MAPI wants to use HKEY_CURRENT_USER to access the registry for profiles. This works fine for any thread running as the same user that the process was run as. However, the predefined HKEY_CURRENT_USER handle, which MAPI uses, will always point to the registry hive of the process' user, not the thread's user. There is a trick (this article was pulled due to the problems described below) to substitute a different registry hive which works if you have full control of all code accessing the registry, but this is rarely true of most applications.
There's another trick to avoiding these registry problems: MAPI_TEMPORARY_PROFILES. This flag causes MAPI to use file based profiles instead of using the registry. However, support for this flag was removed in Outlook 2003, so this trick can only be used with Exchange's MAPI and older versions of Outlook.
Both Outlook's and Exchange's implementations of MAPI depend on several support threads which they will spin up in the course of normal operations. Outlook's MAPI uses support threads for it's implementation of Cancel RPC, and both use support threads to handle notification processing (even when the client has not specifically requested notifications). MAPI creates these new threads using CreateThread. Note that the documentation for CreateThread specifically states that this API should not be used from a thread running under impersonation.
If you're using Exchange's MAPI, then there is a way to switch to a different notification engine which doesn't suffer from as many of these problems. It's documented in XCLN: OWA Clients Receive a "Failed to Connect to the Microsoft Exchange Server" Error Message (323872). Note that the article mentions reg keys such as inetinfo and dllhost. These reg keys would need to be the name of your application in order to work.
MAPI stores “instance data” for each security context that calls MAPIInitialize. The information includes the heap handles, shared sections for interacting with other processes using the same security context, etc. Instance data lives in a structure that is keyed to a hash of the current security context’s SID. So, if you create a MAPI object under one security context and release it under another, MAPI either a) fails to find the instance data and crashes, or b) frees the object from the wrong heap and corrupts the heap. How this instance data is affected by impersonation was also involved in the Deleted Profile issue.
We've seen a number of crashes in code that uses impersonation and then uses MAPI. Many of these relate to heap allocations occurring with one user context and then the deallocations happening with another context. Both the Exchange and Outlook development teams are aware of these issues. However, especially due to the problem with CreateThread, we've not been able to fix all of them.
I had originally stated "Other problems we have seen, especially in code that manipulates profiles prior to logon is OpenMsgStore failing with MAPI_E_FAILONEPROVIDER (0x8004011D) and MAPI_E_NETWORK_ERROR (0x80040115)." After further investigation, it turns out the code that was seeing these problems was creating the profiles by editing MAPISVC.INF, and these file manipulations were not protected properly by a mutex. So one thread's edits of the file were overwritten by another thread's edits before the profile could be configured. Subsequent failures in MAPI were then due to the corrupted profiles.
If you're using impersonation in order to access multiple mailboxes, you may be doing too much work. You can use IExchangeManageStore::CreateStoreEntryID to log on to any mailbox for which you have the appropriate permissions. So for code running under an administrator account with the right permissions, you can use this API to access any mailbox without doing any impersonation.
If you must do impersonation, for example, to connect to different servers where it may not be possible to arrange a single account with the right permissions, then the recommendation is to use a stub program to impersonate, then call CreateProcessAsUser to launch your worker program which does the real MAPI work.
Getting MAPI to work with impersonation is very hard. If you have an application which uses MAPI with impersonation and you're not experiencing problems, congratulations. If you're planning on writing new MAPI code and you think you need to use impersonation, follow one of the above workarounds. I pulled the article (which did nothing more than walk through the mechanics of using LogonUser and leak at least two handles along the way) so as not to encourage new code using MAPI under impersonation.
If you absolutely must use impersonation with MAPI:
Thanks to Dana Birkby and others for reviewing this article.
[Edit - 4/22/05 - 9:30AM - Updated Observed Behavior section]
[Edit - 7/19/05 - 5:35PM - Noted that KB 199190 was pulled]