Inside MAPI Profiles

Messaging API (MAPI) profiles are the primary configuration mechanism for Outlook. Profiles let Outlook know which services are available to the end user and the characteristics of those services. For example, the definition and location of a user's offline folder store (OST) and personal folder store (PST) are stored in the profile. You might need to manipulate the contents of profiles to troubleshoot various problems or, more commonly, when you restructure systems or migrate users to new systems. Although many Microsoft tools (e.g., profgen.exe, newprof.exe) and third-party tools are available, they might not always meet your specific needs. Therefore, you might need to roll your sleeves up and get your hands dirty by manipulating MAPI profiles yourself. Before you do that, you need to understand their structure.

MAPI Profile Structure
A MAPI profile is nothing more than a bunch of registry settings and, as such, can be manipulated using many techniques. In this article, I use regedit to look at the contents of profiles, but before I go any further, I want to issue the following warning: Regedit + human being = time to update résumé. Playing with the registry directly is a dangerous pastime and should be avoided whenever possible. Use documented APIs if available because these will ensure that all relevant parts of the registry are updated. If you do make manual changes, always back up the registry before you start. One technique that I employ is to always export a key before changing it so that I have a .reg file that I can import back in if things don't go as expected.

Profiles are anchored within the registry in either the HKEY_CURRENT_USERSoftwareMicrosoftWindows NTCurrentVersionWindows Messaging SubsystemProfiles subkey for Windows XP, Windows 2000, and Windows NT 4.0 or the HKEY_CURRENT_USERSoftwareMicrosoftWindows Messaging SubsystemProfiles subkey for Windows Me, Windows 98, and Windows 95. Within the Profiles subkey, you'll find a subkey for each MAPI profile that you've defined (you can define as many profiles as you want), as Figure 1 shows. Note that the DefaultProfile string value (type REG_SZ) in the right-hand pane names the current default profile (the Cached profile in this instance). If you wanted to manually change the default profile, you could set this string value to the name of one of the other profiles defined in the Profiles subkey.

Drilling down one more level, as Figure 2 shows, you can see the Cached profile's subkeys and one subkey's associated values. As Figure 2 shows, the names of the subkeys are just a bunch of numbers and letters. A profile is defined in terms of services, and each service has one or more values that define the service's configuration. To ensure that one service's configuration doesn't override another's, globally unique identifiers (GUIDs) are used for the service's subkey name (note that the term section GUID is also used in some documentation).

Many different services—such as Outlook Client Settings, Email Accounts (e.g., POP, Exchange, IMAP), Address Book Details, PST/OST locations, and application-specific settings—can be defined within a profile. Many applications (including third-party applications) manipulate the various registry settings. For example, using the Control Panel Mail applet to manage your own profiles or using Outlook to set the order of address book lookups will update service values in the registry.

You can glean information about a service's MAPI properties from the value names. Each MAPI property has a data type (e.g., Binary, Unicode, ANSI) and an ID, and the alphanumeric values for these two elements form the name of the value that stores the data for the property. The first four characters of the name define the data type (the most common of which are shown in Table 1), and the second four define the MAPI property ID. For example, the value 001E6612 is a string value (001E) for the distinguished name (DN) of the Exchange Home Server (6612).

These registry value names have corresponding MAPI property tags whose values reverse the order of the MAPI property ID and data type (putting the MAPI ID first) and are written in hexadecimal format. For example, the Exchange Home Server property has the tag PR_PROFILE_HOME_SERVER_DN with the hex value &H6612001E. You can find MAPI property tags documented in various sources including Microsoft Developer Network (MSDN). A list of Exchange-specific property tags is at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cdo/html/_olemsg_microsoft_exchange_property_tags.asp.

Service GUIDs
Certain services have static well-known GUIDs; for example, the Exchange Server Details service always has the GUID 13dbb0c8aa05101a9bb000aa002fc45a. If you're familiar with these well-known GUIDs, you can easily locate the corresponding services and their properties within a MAPI profile. For example, if you want to find the name of the Exchange Home Server for every defined profile, you can trawl through the Profiles subkey and, for each subkey, look at the 001E6602 value of 13dbb0c8aa05101a9bb000aa002fc45a. The Outlook Client Settings service also has a well-known GUID: 0a0d020000000000c000000000000046. The Outlook Client Settings subkey is used primarily by pre­Outlook 2000 clients. Later versions of Outlook use the HKEY_CURRENT_USERSoftwareMicrosoftOffice<9.0|10.0|11.0>OutlookPreferences subkey for most client settings, ensuring that they're pervasive across all MAPI profiles.

Other service GUIDs are generated dynamically and are therefore more difficult to deal with. A good example is the creation of a PST file, which results in the generation of a unique service GUID within the profile to which the PST belongs. So how can you tell which service a GUID relates to? Well, most, but not all, services have a name that's held in the property 001f3D09 (Unicode) or, less frequently, in the property 001e3D09 (ANSI). The service name for PST files is MSPST PS; thus, the 001f3D09 value has MSPST PS in its Data field. You could also look at the property 001f6700, which contains the path to the PST file. (The PR_PST_PATH property tag has the hex value &H6700001F.)

Another well-known GUID is 9375CFF0413111d3B88A00104B2A6676, which is used to hold details about all the accounts that are in use within the profile. Under this subkey, you will find a subkey per account. For example, you'll typically find a subkey relating to the Outlook Address Book (OAB) account, the Exchange account, an account for each PST file that's been added to the profile, and any POP3/IMAP mail accounts that are defined within the profile.

Adding a Second Mailbox
Now let's perform a common Outlook function—adding a second mailbox to a profile—and look at the effect on the profile's registry entries. Exchange supports multiple message store providers and by default includes two providers, one for the user's mailbox store and one for the public folder store. The MAPI property for the list of store providers is PR_STORE_PROVIDERS and has a hex value of &H3D000102. Thus, we can discover the message stores that are in use by the profile in question by investigating the 01023D00 value of 13dbb0c8aa05101a9bb000aa002fc45a (the Exchange Server Details service GUID). In Figure 3 the arrows show that the data in this value relates to two other service GUIDs that define the individual store providers for the profile called Cached.

Figure 4 shows how the 01023d00 value changes as a result of adding a second mailbox to the profile—note that I now have a third store provider, indicated by the third service GUID. As Figure 5 shows, the details for this service GUID show that it relates to a mailbox.

Learning the Numbers
Figuring out which service GUIDs and values control which end-user operations is difficult, but a couple of techniques can help you. First, use regedit and export a subkey before and after you make a change to it. Comparing the two output files lets you know which subkey values have changed.

Second, use the Regmon utility, which you can download for free at http://www.sysinternals.com. This utility lets you monitor and capture changes to the registry in real time. For example, I recently wanted to write a script to change users' default mail accounts. I didn't have a clue which registry entry controlled this property, so I fired up Regmon and played around in the Outlook GUI, adding mail accounts to my profile and changing the default account. Regmon pointed me to the well-known service GUID I mentioned above for the list of accounts in use: 9375CFF0413111d3B88A00104B2A6676. Regmon also pointed me to the value {ED475418-B0D6-11D2-8C3B-00104B2A6676}, which kept changing as I experimented. Some simple detective work then revealed that the data associated with this value was a list of subkeys, one for each mail account, in the order the mail accounts were listed in Outlook. With this information, I could write a script to change a group of users' default mail accounts.

Using .prf Files
Outlook supports the /importprf parameter, which allows you to create profiles based on definitions held in text-based Outlook profile (.prf) files. You use the /importprf parameter as follows:

outlook.exe /importprf 

Among other things, a .prf file defines many service GUIDs with associated keys and values that will ultimately end up in the registry. "Whitepaper: Configuring Outlook Profiles by Using a PRF File" describes how to build a .prf file and provides more clues about what all the funny numbers in the registry mean. You can download the white paper at the Microsoft Office 2003 Resource Kit Downloads page at http://www.microsoft.com/office/orkarchive/2003ddl.htm. You can also generate .prf files by using the Custom Installation Wizard in the Office Resource Kit, which is available at the same Web page.

Manipulating MAPI profiles directly is certainly not something that anyone would choose to do for fun. However, understanding the MAPI profile structure can help you in troubleshooting situations and can lead to the discovery of innovative solutions to migration problems that might at first seem difficult to solve.