Call MrMAPI, That’s My Name, That Name Again Is MrMAPI!

  • Article

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!