August, 2012

The August 2012 Release (build 15.0.0.1035) is live: http://mfcmapi.codeplex.com.

In honor of the Outlook 2013 Preview, this month I’ve decided to turn MFCMAPI blue. Along the way, I was able to fix a number of nagging flicker issues, as well as fix the system button placement on XP systems. However, the changes I made for Outlook 2013 weren’t just cosmetic. As you may have noticed in the updated MAPI Reference, it’s now possible to have more than one version of Outlook installed on a machine at the same time. This poses a problem for MFCMAPI: which MAPI to load? To solve this problem, MFCMAPI locates all the implementations of MAPI it can and puts them on a menu. You’ll find this under Session/MAPI Initialization/Load MAPI. Of course, if you’re happy with the default MAPI, you don’t to do anything different. If you’re interested in seeing how MFCMAPI looks for MAPI implementations, consult stubutils.cpp and the MAPIPathIterator class.

[Edit] How could I change the UI (again) without posting a screenshot?

Here's a change list - see the Issue Tracker on Codeplex for more details, or look at the code:

• MrMAPI: fixed a parameter parsing crash
• MFCMAPI: Corrected location of system buttons on some WIndows XP systems
• MFCMAPI: Found and corrected a number of minor flicker issues
• MFCMAPI: Implemented a blue highlight
• MFCMAPI: Much better handling of the OLE attachment type
• MFCMAPI: Click-to-Run and side-by-side support for the Outlook 2013 Preview

Enjoy.

As you know, when you install a new provider on a system, you have to update MAPISVC.INF to point it to the new provider. There are a few standard properties set during this configuration which tell MAPI where to find your DLL. One is PR_SERVICE_DLL_NAME, set in the Message Service section, and the other is PR_PROVIDER_DLL_NAME, set in the Service Provider section. For both properties, you are expected to set the name of your provider’s DLL (minus the “32” suffix"). MAPI will then load your provider by looking for it on the path.

What if the path isn’t good enough? What if, like any other modern application, you want to drop your provider over in Program Files and not dirty the path? According to the MAPI documentation, you shouldn’t be able to do that. However, it turns out that, with a few restrictions, Outlook’s MAPI can deal with full paths to MAPI providers. Outlook development has agreed to support this for Outlook 2010 and higher.

Here are the particulars:

• When registering your provider in MAPISVC.INF, you should put the full path to the provider in PR_SERVICE_DLL_NAME and PR_PROVIDER_DLL_NAME.
• Further, in a store provider, you will from time to time generate entry IDs using WrapStoreEntryID, which takes as a parameter the name of your provider. If you’re using full paths in MAPISVC.INF, you must use the same path in WrapStoreEntryID.
• In both cases, this full path must be without the “32” suffix, as MAPI will continue to append it before looking for your file. So if you register the path “c:\mypath\myprovider.dll”, MAPI will try to load “c:\mypath\myprovider32.dll”.
• Because Outlook’s MAPI was not originally designed with full paths in mind, it does this insertion of the “32” by looking for the first period in the string. This means that paths which contain other periods cannot work. So you cannot use paths such as “c:\my.groovy.path\myprovider.dll” or “c:\mypath\my.groovy.provider.dll”.
• The path you use may be converted to and from Unicode using the code page provided by GetACP. You will see failures if you choose a path which contains characters cannot survive such a roundtrip through MultiByteToWideChar/WideCharToMultiByte.

To demonstrate this, I’ve updated the Wrapped PST sample over on Codeplex. The magic happens in MErgeWithMAPISVC and GenerateProviderPath.

Enjoy!

A customer just raised this issue with our Wrapped PST provider sample. They were trying to retrofit the sample to use Unicode paths to the NST and found that the CreateStoreEntryID routine was producing an invalid entry ID after they changed to to use a Unicode path. Through experimentation, they were able to produce a valid entry ID and wondered if I could document the necessary format. It turns out we use two different formats for the entry ID of a wrapped PST. One format is for ASCII paths and the other is for Unicode paths. Here they are, represented as structures:

typedef struct				// short format

{

	BYTE		rgbFlags[4];	// MAPI-defined flags

	MAPIUID		uid;		// PST provider MUID

	BYTE		bReserved;	// Reserved (must be zero)

	CHAR		szPath[1];	// Full path to store (ASCII)

} EIDMS;

// Unicode version of EIDMSW is an extension of EIDMS

// and szPath is always NULL

typedef struct				// Long format to support Unicode path and name

{

	BYTE		rgbFlags[4];	// MAPI-defined flags

	MAPIUID		uid;		// PST provider MUID

	BYTE		bReserved;	// Reserved (must be zero)

	CHAR		szPath[1];	// ASCII path to store is always NULL

	WCHAR		wzPath[1];	// Full path to store (Unicode)

} EIDMSW;

The net effect of the difference in these structures is there are two NULL bytes prior to a Unicode path. If you’re interpreting the entry ID, one way to determine how to interpret it would be to cast it as EIDMS first, then check if szPath[0] is NULL. If it is, you need to cast it as EIDMSW instead.