November, 2010

A couple of days ago, we published an update to the Outlook 2010 MAPI reference. Rather than try to summarize everything we did, here’s the mini press release Randy sent out to announce that we were done:

My involvement in this project was as tech reviewer and author of MFCMAPI. I tried to shove as much of the new documentation into MFCMAPI as possible, including SmartView parsers for PidLidPropertyDefinitionStream and PidTagUserFields, both of which have been long standing requests. I also wrote or contributed to many of the code samples. The bulk of the work though was done by a small crew of folks on the Office Content Publishing team who know so much more about content than I could ever hope to know. They did an excellent job.

As always, feedback is welcome.

Enjoy!

I said yesterday that MrMAPI deserved a full post, so here it is.

MAPI has a lot of property tags. You’ll find lists of them in the MSDN, and a number of them are documented in various and sundry KB articles. The problem with this documentation is that it’s of very little use when you’re debugging a GetProps call, trying to figure out what the property 0x0E6D001E is, or when you’re trying to remember an interesting property you read about, but all you know for sure is that the name of the property had the word “street” in it. For years, we had internal Microsoft only tools that were of some help in this – they were built from the Exchange or Outlook source and included in them a large number of properties that you could look up. With these tools, you could look up a property by tag number and learn its name. They also provided limited support for searching in the other direction, looking up a property by name and learning its tag.

The problems I had with these internal tools were twofold:

1. They didn’t know every property.
2. They were internal only.

I tackled the first problem in two phases. Over the years I had been hand tuning arrays in MFCMAPI that consisted of every property we’ve ever documented in the MSDN, in KBs or in blogs. Using these as a baseline, I wrote Perl scripts to search the Exchange and Outlook source trees for anything that looked like a property and built augmented arrays of every property ever in existence. With these in hand, I built a tool I dubbed MrTag. This tool has been very successful here in support, as well as over in the product team where they use it to check on availability of unused property tags. We still had the problem that the tool was internal only, since it contained internal information.

Now – I originally planned to take the arrays from MFCMAPI and build an external version of MrTag, but that would have been yet another project for me to support and manage. Then inspiration struck – I could code up a command line for MFCMAPI and just let MFCMAPI do the work! Unfortunately, it’s not possible to add a command line interface to a Windows application that works as I expect a command line tool to work. That is, if I pass command line parameters, I want the output to display back in the command window. Maybe I’ll write up the reasons for that later. I finally settled on adding a new project configuration to the MFCMAPI project that builds strictly as a command line tool with no Windows UI. I then just had to port the property lookup logic from MrTag, and MrMAPI was born! Now the world has access to a first class property lookup tool, and I have less code to maintain. Everybody wins! Since this tool is just a variant build of MFCMAPI, as I add and tweak the property lists, it will stay up to date.

Enough history – here’s how to use MrMAPI. I’ve excerpted part of the command line help:

MrMAPI [-S] [-D] [-N] [-T <type>] <number>|<name>
Property Tag Lookup:
-S   Perform substring search.
        With no parameters prints all known properties.
-D   Search dispids.
-N   Number is in decimal. Ignored for non-numbers.
-T   Print information on specified type.
        With no parameters prints list of known types.
        When combined with -S, restrict output to given type.

Without any switches, MrMAPI just looks up the property number or name, so you can look up 0x0037 or PR_SUBJECT and get results. You use the –S switch to perform a substring search. This is how you’d find that property that had street in it’s name. With no string, it will give you a list of every property that MrMAPI knows – nearly 4 thousand of them. If for some reason the property number you’ve run across is in decimal, you can use the –N switch to indicate this. The –D switch allows you to look up named properties – something our other internal tools never supported. The term dispid comes from the fact that most of the named properties begin with dispid, such as  dispidReminderNextTime. In recent years, we’ve started giving these properties names beginning with PidLid, much as we’ve started giving property tags names starting with PidTag. MrMAPI is comfortable with both naming conventions, and if you look up a property using one name it will always tell you the other.

The –T switch is interesting. On its own, it can be used to print a list of MAPI property types. Combined with a search, we can restrict our output by type. So, for instance, if we wanted to find a PT_LONG property with “address” in it, we could use the switched “-s address –t PT_LONG”.

If you’ve played with MrMAPI a bit, you’ve probably noticed I’ve only covered half of what it can do. The other thing it does right now is SmartView parsing from the command line. For day to day use, if you’ve got a hex string you want to parse with SmartView, MFCMAPI’s Hex Editor (Ctrl+H) is probably more convenient. The command line SmartView parser is prep work for some automated analysis tools we’re working on. It also allowed me to write some test cases for the SmartView parsers, since I’m finding that the parsers are easy to break if I’m not careful. I plan to do a lot of work in this area and will talk about it more later when it becomes more interesting.

Hopefully you will all find MrMAPI to be useful. I’m very interested in getting feedback. If you find a flaw in the way it works, or find that we’ve documented a property that it doesn’t know about, please let me know so I can fix it. You’ll always find the latest version of MrMAPI on the download page for the latest release of MFCMAPI.

Enjoy!

The November 2010 Release (build 6.0.0.1023) is live: http://mfcmapi.codeplex.com. I’m also excited to announce the release of MrMAPI at the same location.

MFCMAPI work this round consisted of one new SmartView parser and a smattering of small features and bug fixes. The really exciting work was rebuilding MFCMAPI into a command line tool I’d dubbed MrMAPI. MrMAPI exposes two of MFCMAPI’s best features from the command line: Property tag lookup and SmartView parsing. It really deserves a blog entry of it’s own but for now, here’s a taste of what it can do:

C:\>mrmapi 0x3001001E
Property tag 0x3001001E:
Exact matches:
0x3001001E,PR_DISPLAY_NAME,PT_STRING8
0x3001001E,PR_DISPLAY_NAME_A,PT_STRING8
0x3001001E,ptagDisplayName,PT_STRING8
Partial matches:
0x3001001F,PR_DISPLAY_NAME_W,PT_UNICODE
0x3001001F,PidTagDisplayName,PT_UNICODE
C:\>mrmapi -s last_mod
Searching for "last_mod"
0x0E590102,PR_LAST_MODIFIER_SID,PT_BINARY
0x0E6D001E,PR_LAST_MODIFIER_SID_AS_XML,PT_STRING8
0x30080040,PR_LAST_MODIFICATION_TIME,PT_SYSTIME
0x3FFA001E,PR_LAST_MODIFIER_NAME,PT_STRING8
0x3FFA001E,PR_LAST_MODIFIER_NAME_A,PT_STRING8
0x3FFA001F,PR_LAST_MODIFIER_NAME_W,PT_UNICODE
0x3FFB0102,PR_LAST_MODIFIER_ENTRYID,PT_BINARY
0x80B40040,PR_EMS_AB_GWART_LAST_MODIFIED,PT_SYSTIME
Found 8 matches.

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

• SmartView: Parse PR_LAST_MODIFIER_SID
• Profile: Added the ability to set the default profile
• Export: Export to text now sorts the properties by tag first
• Recipients: Reworked the Recipient table editor to make updating recipients much easier
• MrMAPI: New tool, MrMAPI.exe, enables property tag lookup on the command line
• MrMAPI: New tool, MrMAPI.exe, enables SmartView parsing from the command line
• Bugs: Found and fixed a number of crashes

Enjoy.

I just got back from a vacation to Italy, Greece and Turkey. While I was out, we shipped a new update for the MAPI download. I got a number of requests for release notes, so here we go.

Installation details:

• This version is 6.5.8190.0. Most files in the update are dated October 7th, 2010, with a few dated on the 4th.
• If you already have a version of the MAPI Download installed, you must uninstall it before installing the new version. The installer does not upgrade, nor does it warn you if you try to install it without uninstalling the previous version.

Fixes:

• Hang in emsmdb32 during shutdown: More precisely, this is a high CPU hang with both the client thread and a background thread each waiting for the other to complete some work. The background thread will be calling Sleep in a loop.
• Thread handle leak: To see this one, you need code which logs on and off of mailboxes in a loop. Using Perfmon, you can track the thread handle count getting higher and higher, without the actual thread count increasing. This issue may also manifest as 9646 errors on the Exchange server.
• Intermittent MAPI_E_NETWORK_ERROR from random MAPI calls while multithreading: MAPI_E_NETWORK_ERROR is a legitimate error which can crop up for a variety of non-MAPI-bug reasons (such as, say, a router eating packets), but this one was a specific issue in how emsmdb32 handled tearing down connections. Essentially, closing one connection was closing all of them, causing successful connections to become non-functioning.
• First chance AV during emsmdb32 unload: This is the issue I mentioned before that wasn’t fixed in 8165.

Enjoy!