On this page, talking about eh Upload Folder State, we have a note which references the constant UPS_ONE_FOLDER. This constant is not defined in our list of MAPI Constants or in a header file. This is an oversight. Here’s the definition for this constant:

#define UPS_ONE_FOLDER 0x00000004

The April 2012 Release (build 15.0.0.1033) is live: http://mfcmapi.codeplex.com.

I ship a new build of MFCMAPI every two months. That’s a personal goal I keep to help motivate me. Somehow I got it in my head that I was due to release a new build of MFCMAPI here in April. So I worked extra hard to track down some bugs and implement some new features to make the new build worth it. Only when that was done did I realize I shipped a new build in March – one month ago. So here you go – bonus build!

When you start this new build, you’ll see a new menu, which is a feature I’m quite proud of: QuickStart. This is a collection of actions that will get you to common destinations in MFCMAPI with a minimum of fuss. For instance, you can now in one action open the Inbox, Calendar, or Contacts folders. Other QuickStarts I implemented in this first batch are one to display the contents of your nickname cache (this one can be slow) or display your mailbox quotas (several properties which are a pain to track down since they’re not visible by default). Over time I plan to add more QuickStarts to the list, so send me any idea you have and I’ll consider them.

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

• QuickStarts
• SmartView: Fixed Recurrence Blob parser crash
• Added Copy/Paste to profiles – back up a profile before you fiddle with it!
• MAPI Stub Library Overhaul: We simplified the stub library code and now MFCMAPI benefits.
• Fixed a couple New Look glitches.

Enjoy.

If you’ve ever tried to use MFCMAPI to troubleshoot Exchange server mailbox quotas, you’re probably familiar with the properties PR_STORAGE_QUOTA_LIMIT, PR_PROHIBIT_SEND_QUOTA, and PR_PROHIBIT_RECEIVE_QUOTA. These properties live on the message store object and tell you what your various quotas are. The problem with these properties is that they only work with an online profile. If you’re working with a cached mode profile, these properties will not work. Prior to Outlook 2010, the only workaround was to either build an online profile or bypass the cache. As of Outlook 2010, there’s another option. The OST in Outlook 2010 exposes three properties which contain the same quota information as the online only properties. Development just gave me permission to document them:

#define PR_QUOTA_WARNING PROP_TAG( PT_LONG, 0x341A)
#define PR_QUOTA_SEND    PROP_TAG( PT_LONG, 0x341B)
#define PR_QUOTA_RECEIVE PROP_TAG( PT_LONG, 0x341C)

These properties map exactly to the corresponding online properties and should contain the same values, in kilobytes. So PR_QUOTA_WARNING maps to PR_STORAGE_QUOTA_LIMIT, PR_QUOTA_SEND maps to PR_PROHIBIT_SEND_QUOTA, and PR_QUOTA_RECEIVE maps to PR_PROHIBIT_RECEIVE_QUOTA.

BTW, for completeness, if you’re looking at any of the above properties you may also be interested in PR_MAX_SUBMIT_MESSAGE_SIZE, which is the largest a message can be for submission, in kilobytes, and PR_MESSAGE_SIZE_EXTENDED, which is the size of the mailbox in bytes. Both of these properties function in cached as well as online profiles.

Enjoy!

A while back I mentioned our MAPI Stub Library. This is a couple of .cpp files you can drop in to your project instead of linking to mapi32.lib, Alternatively, you can build your own version of mapi32.lib. You can read more about the whys and wherefores on the codeplex site or in the MSDN article on MAPI linking.

We just updated the logic used to find the correct MAPI binary to both make it more correct and to simplify it. According to the dev who did the work, we were able to eliminate two thirds of the code from StubUtils.cpp. The code is now more future proof, so if you were using the original version, you should look at incorporating the update. MFCMAPI will use this new logic in its next build.

Enjoy!

From time to time, folks ask me what they need to do in their message store provider to support Outlook 2010’s conversation view. I tell them they need to support restrictions on message store tables as discussed in the MAPI documentation. If Outlook hands them a restriction, they can’t return MAPI_E_TOO_COMPLEX and expect the conversation view to work. I also tell them their table needs to support categorization with multivalued columns and MV_INSTANCE. Because they support categorization, they also need to return STORE_CATEGORIZE_OK in PR_STORE_SUPPORT_MASK. Basically, when you turn on a conversation view, Outlook is going to exercise more of the MAPI spec than it has before. If your provider can’t handle it, then the view won’t work.

This is all true, but as usual, there’s more to the story. The more comes about when you decide your store isn’t going to be able to handle conversations. We usually find that categorization is the feature most people have trouble getting to work. So they decide “Ok – we just won’t support conversations” and they don’t return STORE_CATEGORIZE_OK. Their store works fine in Outlook, until a user tries to configure a conversation view. Then the user gets the error “Cannot display information. There is a problem connecting to the server or an error occurred. Try starting Microsoft Outlook again.” They continue to get this error until they change to a different view.

What’s going on? When we implemented the conversation view, we took a dependency on the categorization feature working in order to get the view working quick enough to be acceptable to the user. We also implemented a fallback path in case categories weren’t implemented, but since all of our built in providers did implement categories, this path did not get well tested. In fact, there’s a logic bug in it that causes the error the user sees. We investigated this a while back and even attempted a fix. However, when we did this, we realized why having categories was so important. Without categories, the performance of the conversation view is, to be blunt, horrible, Categories, it turns out, were what allowed us to implement the conversation threads without incurring a high level of post processing on the table.

We decided we couldn’t fix that code path (or we technically, we could, but no one would want the fix), and we looked at alternatives for delivering a better experience. The obvious choice here is to disable the conversation view UI when the store doesn’t support categories. However, this presents a challenge – we didn’t consider in our original design how to handle multiple stores where some stores (like the PST) support the view but others don’t. So while we agreed this would be a good design change, it was deemed too expensive to consider in a hotfix or service pack.

One customer found that, through heavy customization of the ribbon, they could hide the UI themselves when the user was looking at one of their folders, but leave the UI enabled when someone else’s folder was selected. However, it was still possible to set a conversation view to one of their folders. This could happen because of a prompt we display when the user checks “Show as Conversations”:

If the user picks  “All folders” here, the conversation view gets applied to the store that couldn’t support it. Fortunately, there’s a way to suppress this dialog. We have a policy, UpgradeToConversations, which controls conversion to/from the conversation view. 0 converts conversation views to date sorts, 1 converts them the other way, and 2 says leave them all alone. If this policy is set to any value, we don’t display the prompt. For the customer that customized the ribbon, setting the policy to 2 allowed their users to have conversation views in the PST and Exchange stores, but not get them set in their store.

The moral of this story is if you have a custom store provider, you really need to support categories if you want your users to have a good experience.

We did it! MFCMAPI is now on Wikipedia!

The March 2012 Release (build 15.0.0.1032) is live: http://mfcmapi.codeplex.com.

No UI changes this round, so no new screenshot. I did fix some interesting bugs and added a few nice features. Probably the nicest feature is new MAPI call logging. I‘ve always had error call logging in MFCMAPI via the Debug Viewer (Ctrl+D), but I never had a way to output exactly which MAPI calls were being made, whether they failed or not. Now you can get that – just turn on tag DBGMAPIFunctions (0x40000000) in the Debug Viewer and you’ll see every MAPI call that gets made. If you want more perspective on an error, I’d also add DBGGeneric (0x1) and DBGHRes (0x40). You can use 0x40000021 to turn on all of these at the same time.

Oh – and perhaps the biggest change of all: All the binaries are now code signed!

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

• Added MAPI call logging.
• SmartView: Added parsing for dispidVerbStream.
• MrMAPI: –Store switch will output store properties.
• MFCMAPI: New dialog to display which MAPI dll is loaded.
• Eliminated non-standard line endings in files MFCMAPI and MrMAPI can generate.
• Cleaned up the MAPI loading code – should work better in more odd scenarios.
• Code signed!

Enjoy.

We’ve added a couple new C++ only events to Outlook 2010 which I have been asked to document. These events were added per customer request to help fill some gaps in the transition from ECE to Com Add-In. One of the events is available as of the October 2011 Cumulative Update, and the other just shipped in the February 2012 Cumulative Update.

The two new events are:

If you’re familiar with writing Exchange Client Extensions and Com Add-Ins in C++, this is likely sufficient information to handle these events. If not, you might want to review some samples which demonstrate handling events from the IDispatch::Invoke function. For example, I found this add-in on codeproject which handles Application events. In that code, the CAppEventListener::Invoke function is where you would handle the BeforePrint event.

Some notes:

• Both of these events are cancellable. The first parameter is of type VT_BOOL|VT_BYREF. Return VARIANT_TRUE in this parameter to cancel the operation being signaled by the event.
• BeforePrint has an extra second parameter. This is a mistake on our part, which unfortunately cannot be corrected. Just ignore it.
• I characterize these as C++ only events to stress that they are not part of the type library and therefore not exposed to languages and frameworks which handle IDispatch for you. You can handle these events if you implement IDispatch directly, which may be possible from languages other than C++.

Enjoy!

This week, we shipped the February Cumulative Update for Outlook 2010. One of the fixes in there relates to the MAPI<->MIME conversion API. In particular, with Outlook 2010 if you use MAPIToMIMEStm to convert a message to EML you’ll see the source message get updated. This didn’t happen with Outlook 2007. The reason for the change in behavior has to do with how we handle conversation threading, particularly for messages that don’t already have some of the conversation properties already stamped on them. In order to preserve threading should the MIME message come back in to MAPI (a scenario which occurs with POP3/SMTP profiles and replies), we would stamp the conversation properties on the source message during the export.

In general, this is fine, but it did cause a problem for some vendors who needed their export to not modify the source. So for them, in the February CU we enable a new flag:

#define CCSF_PRESERVE_SOURCE  0x40000 // don't modify the source message

Pass this new flag in to MAPIToMIMEStm and we’ll bypass the new code that saves changes back to the source message.

One caveat: We may still make changes to the message. This flag skips the SaveChanges call that commits the changes. So if your code subsequently calls SaveChanges, you’ll see the changes made during the export get committed. Of course, if your code is calling SaveChanges, you probably won’t be using this flag in the first place.

Enjoy!

Remember Jason’s article about the reconnect logic we added to Exchange’s MAPI? The idea was that if your GC went down, Exchange’s MAPI should be able to reconnect to a different GC and proceed smoothly. Mostly smoothly though, since the last call sent to the old GC may fail with MAPI_E_END_OF_SESSION and need to be retried. What was left unsaid from that article was that if you’re using Outlook’s MAPI, which supports reconnect without special configuration, there are some other error codes that can bubble up to the client. Development has given me permissions to document a couple that have shown up in the wild:

#define MAPI_E_RECONNECTED MAKE_MAPI_E( 0x125 ) // 0x80040125
#define MAPI_E_OFFLINE MAKE_MAPI_E( 0x126 )  // 0x80040126

MAPI_E_RECONNECTED, aka 0x80040125, is returned by the Exchange Address Book and Message Store providers when the RPC connection token is discovered to be out of date. The connection token is basically a number tracking the current connection. If the token on our current transaction is different from the token on the connection, this means we have reconnected, so MAPI_E_RECONNECTED is returned. MAPI_E_RECONNECTED can be treated the same as MAPI_E_END_OF_SESSION and the call should be retried.

MAPI_E_OFFLINE, aka 0x80040126, is returned by the Exchange Address Book and Message Store providers when we discover that we are offline. Typically this means that something has happened in the environment, such as a server going down, or loss of network connectivity. This error is most likely to occur when using a cached mode profile and attempting to bypass the cache to talk to the server. If the cache was never able to establish a connection to the server in the first place, we may be in this offline state where MAPI_E_OFFLINE could surface.

Neither one of these errors will be returned in all scenarios where it would appear they would appear to apply. In most cases, MAPI_E_NETWORK_ERROR or MAPI_E_CALL_FAILED will be returned instead. But now if you do get one of these errors you know what it means. Both of these errors are specific to Outlook’s MAPI only. They will not appear with MAPICDO.

Enjoy!

This was an interesting scenario one of our customers came up with. They process a lot PSTs. As part of this processing, they create search folders and wait for them to complete building. They found that for many PSTs, they would never get a notification that the search folder had finished building.

Here’s the basic outline of what they were doing:

1. Their application starts and they load a PST.
2. Register an Advise Sink for fnevSearchComplete.
3. Create a search folder using CreateFolder with the FOLDER_SEARCH flag.
4. Apply search criteria using SetSearchCriteria.
5. Wait for fnevSearchComplete.

Usually this worked, but occasionally their application would end up stuck in step 5 waiting for the search folder completion. What was really strange is that if we opened MFCMAPI to look at the stuck search folder, after some poking around their application would suddenly get the completion notification!

To understand what’s going on here, we need to know a little bit about how the PST handles searches. There are two basic ways a search can be fulfilled. The most common way currently is that the PST provider leverages Windows Search to handle the search for it. That’s the default configuration, and the customer’s code always worked when it was enabled. But Windows Search can be turned off. This is when the customer’s code would have problems. Without WIndows Search to do the work for us, the PST provider falls back to the mechanism it always used before Windows Search existed: on a background thread it manually does the search and populates the search folder. It’s the handling of this background thread where we were having problems.

When you first load the PST provider, it spins up an idle thread which handles background processing such as search folder generation and updates. Since a PST can be loaded in multiple processes, with only one process actually loading the file and the various processes negotiating reads/writes through shared memory, every process which opens a MAPI profile is a candidate to be the one who manages searches. So every search folder has a process which is considered to be the owner of the search. This owner can go away, in which case the search is orphaned, and a new owner has to be selected. Originally, this was the first process who’s idle thread detected there was a search without an owner which needed to be processed. This, however, caused a problem with short lived processes. Suppose you have a processes that needs to get in and out of MAPI fairly quickly, such as to send an e-mail. This process could unwittingly become the owner of a search, meaning it’s on the hook to stay around and process the search, even though there’s little chance it will benefit from it. This caused problems, so we introduced a delay. If the PST provider has been loaded less than 5 seconds, we won’t try to take ownership of a search.

This is where the customer’s application got in trouble. They started up and got through to the SetSearchCriteria so quickly their idle thread decided it shouldn’t handle the search. And since they were doing nothing else while they were waiting, nothing ever kicked the idle thread back to life to realize there was an unfulfilled search. When MFCMAPI ran, clicking around in the UI was enough for MFCMAPI’s idle thread to spot the search and complete it. This is not to blame their application – they did everything right and nothing wrong. They just managed to walk the narrow tightrope needed to see this problem.

So – how can they avoid the hang? One workaround is obvious – Sleep for 5 seconds before creating search folders. But that’s a performance hit and nobody wants that. Fortunately, there’s a bypass for the delay. If your MAPI session was created with MAPI_BG_SESSION, we assume you’re not just some client sending e-mail, so we grab any search your process is eligible to process the first time we see it.Note that the documentation for MAPI_BG_SESSION indicates “A client application such as an indexing engine or opening a Personal Folders File (PST) for background type access are some examples of where to use MAPI_BG_SESSION”. This is precisely the sort of scenario where we intend this flag to be used.

The customer tried this flag in their code and it worked perfectly. Yay!

No one’s taking my subtle hints about Wikipedia. One more try: It sure would be nice if someone added MFCMAPI to the article about MAPI.

The January 2012 Release (build 15.0.0.1031) is live: http://mfcmapi.codeplex.com.

I’m continuing to crunch on the UI overhaul. This release has a ton of fixes for various flicker issues and glitches, especially those which show under the Windows Classic theme. Most of the problems were bad assumptions on my part that the Classic Theme helped expose. I also worked a good bit on making my various dialogs more pretty, practically rewriting the layout engine in the process. Finally, I finished up my work on painting the system buttons. This last bit required a bit of kernel debugging to figure out why Windows liked to repaint on top of my icons when I moved the mouse around. It turns out that initialization of the window’s system menu is what caused this. If you’re interested, look at how I handle WM_CREATE.

I’m continuing to tweak the colors. Here’s another hero screenshot highlighting the new new color scheme, including the new system buttons:

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

• MFCMAPI: Rewrote/cleaned up most of the dialog rendering
• MFCMAPI: Much more double buffering to reduce flicker
• MFCMAPI: Custom system icons
• MrMAPI: New –Restrict switch to limit output from folders
• MFCMAPI: Softer color scheme
• MFCMAPI: Fixed all known Classic Theme glitches
• SmartView: Added PidTagRoamingBinary
• MFCMAPI: Much smaller options dialog now scrolls.

Enjoy.

What’s an app got to do to get on Wikipedia? You know I can’t put it there myself – that’s against the rules.

The December 2011 Release (build 15.0.0.1030) is live: http://mfcmapi.codeplex.com.

When I started working on the UI overhaul, I knew it was going to take a few releases to get it right. After all, I’m a one man development team, and while I’ve got a number of folks who do testing for me, I can’t catch everything. Since the last release, I’ve found (or been pointed at) a number of issues with the new UI, mostly relating to the abundance of themes out there. I’ve also found a new (to me) code analysis tool which has uncovered a number of potential issues. So I’ve decided to release an off schedule build to address everything. I’m still not done with the UI, but this release should be more visually stable on more machines.

Since I’ve changed some colors in this release, I took a new screenshot:

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

• MFCMAPI: Border painting was weird on some systems (never figured out exactly which, but did find my math error).
• MFCMAPI: Underlying window bleed through in About dialog without Aero (fixed)
• MFCMAPI: Clipping in the tree control as we hover highlight
• MFCMAPI: Color choices conflicted with certain themes (switched to system colors which should not conflict)
• Function annotations: Fixed a number of annotation and signature issues.
• Other sundry code sanitation issues.

Enjoy.

Matt has just announced that EWSEditor has been updated and moved over to Codeplex. Read his announcement here, then go download EWSEditor here.

Enjoy!

We had a customer recently who was using Outlook 2010’s MAPI in their application to talk to the Exchange server. They wanted to enable Kerberos authentication, but were having trouble enabling it programmatically. They had found the property that gets changed when you enable Kerberos authentication through the UI: PR_PROFILE_AUTH_PACKAGE in the global profile section gets set to RPC_C_AUTHN_GSS_KERBEROS. When they tried setting this value in their profile though, they’d find that OpenAddressBook would return MAPI_W_ERRORS_RETURNED and subsequent calls to ResolveName would return MAPI_E_CALL_FAILED. What was really strange was if they opened the profile using Outlook or MFCMAPI, the profile would somehow be “fixed”, and their application would work.

By comparing the profile before and after “fixing” it, we were able to track the difference down to a single property, which development has given me permission to document, PR_PROFILE_HOME_SERVER_FQDN (0x662A001F). This property is located in the address book section, dca740c8c042101ab4b908002b2fe182 (aka muidEMSAB). Setting this property to the DN of the user’s directory server was sufficient to turn a non-working profile into a working profile using Kerberos authentication. For example, if my DC was named ExampleDC, I might set this property to “ExampleDC.example.com”.

So why would running MFCMAPI or Outlook fix the profile? It all has to do with the flags the customer passed to MAPILogonEx. They were passing MAPI_NT_SERVICE. To the Exchange address book provider, this indicated (among other things) that we should not load our user interface (UI) support object, since we’re running in a context that doesn’t allow UI. Later, when we’re attempting to connect to the server, we check if we have been referred to a DC yet. This is the PR_PROFILE_HOME_SERVER_FQDN property. Finding this property not set, we enter the code that would normally request a referral from the Exchange server. However, this code is dependent on the UI support object, so it does not execute. Ultimately, we decide to just talk directly to the Exchange server and let it handle proxying our calls over to the DC as needed.

This all works fine as long as we’re not using Kerberos authentication. However, as we saw in the Check Names article, you cannot use Kerberos to make address book calls to the Exchange server (Exchange 2010 may fix this, but I believe this customer was using Exchange 2007). That’s why setting PR_PROFILE_HOME_SERVER_FQDN fixes the problem, since we connect directly to the DC.

Notes:

• Exchange 2010 handles address book calls made to the CAS differently from how Exchange 2007 and earlier handle them. The DSProxy process is no longer used. So the Kerberos authentication may succeed. However, the client would still be talking to the Exchange server instead of directly to the DC, which may not be desired. Setting PR_PROFILE_HOME_SERVER_FQDN will avoid this.
• Logging on without MAPI_NT_SERVICE sets additional properties besides  PR_PROFILE_HOME_SERVER_FQDN, but investigation has not shown any of them to be essential. I’ll update this post if this changes.

Enjoy!

Still no mention of MFCMAPI on Wikipedia. I had such high hopes. Sigh.

The November 2011 Release (build 15.0.0.1029) is live: http://mfcmapi.codeplex.com.

Note that build number. That’s right. I jumped all the way from 6 (where I’ve been stuck forever) to 15. That’s the sort of jump that’s normally only accompanied by a full UI refresh. And that’s exactly what you get! I’ve overhauled just about every aspect of the UI for a more modern, some might say “Metro inspired”, look. I’ll admit, there’s still some work to be done (I didn’t get to scrollbars for instance) but this is a pretty good start. Let’s take a look:

[See the new screenshot here.]

I’ve drastically slimmed down the menus, stuffing most of the little used functionality into Advanced menus that most of you will never need to open. The old, usually empty, File menu is gone and Session now takes prominence. This should help new users immensely. Long time users of MFCMAPI may want to spend a little time figuring out where their favorite features went, but nothing’s been cut.

A note about the tree: In the past, whenever you selected or expanded a folder, MFCMAPI would register for notifications on that folder and a number of it’s child folders. This was represented in the UI by bolding the folder name. This just confused people, so now, the only time I bold a folder name is to represent the currently selected folder. You can tell if MFCMAPI is listening for notifications on a folder by looking for a little red “I’m listening”icon after the folder name. It looks like this:

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

• MFCMAPI: The entire UI (save scrollbars) has been updated with our new look.
• MFCMAPI: The menu system has been given a long overdue scrub and overhaul.
• MFCMAPI: The links in the help are now clickable.
• MFCMAPI: Options shortcut – Ctrl+O brings up the newly slimmed options dialog.
• MFCMAPI: While reskinnng the tree view I found several opportunities for performance enhancements. The tree should load faster, with less chatter to the server, and fewer issues with refresh as notifications come in.
• Hex Editor: I’ve added commas (,) to the list of ignored characters for hex strings, making importing hex from other applications simpler.
• Debug Viewer: Cancel has been replaced with Close, which makes much more sense.
• MrMAPI: I’ve added pbGlobalProfileSectionGuid to our guid list

Enjoy.