Programmatically Accessing the Nickname Cache in Outlook 2010

  • Article

I recently chatted with our MAPI expert Stephen Griffin and would like to share what I learned about the Outlook nickname cache.

The nickname cache is the list of recipient names that is displayed when you insert names in the To, Cc, or Bcc field in an Outlook email or meeting request. The nickname cache expedites completing a recipient’s name, and is also known as the autocomplete stream.

In Outlook 2010, the autocomplete stream is stored as a MAPI property, PidTagRoamingBinary, of a hidden message in the Associated Contents table of the Inbox of the mail account’s delivery store. This hidden message has a message class and subject of IPM.Configuration.Autocomplete.

In an Outlook session, Outlook only loads and saves the autocomplete stream as a property of the hidden message at most once, and interacts with a copy in memory during the Outlook session. Outlook loads the autocomplete stream into memory when the user, for the first time in that Outlook session, attempts to insert recipients in an email or meeting request. Outlook reads all of the contents of the PidTagRoamingBinary property as a binary stream into a structure in memory. After loading the stream into memory, Outlook only accesses the copy in memory. If the copy is modified during that session, upon Outlook shutdown, Outlook saves the copy back to the hidden message in the Associated Contents table of the Inbox of the mail account’s delivery store.

During an Outlook session, the autocomplete stream in memory can be modified in various ways including the following:

  • The user indirectly adds a new autocomplete entry, through resolving a name, picking a recipient from the address book dialog, or sending mail to a recipient that was not already in the list.
  • The user modifies an entry by sending mail to an existing recipient in the list.
  • The user removes an entry through the autocomplete drop-down list user interface.

Only if the in-memory copy of the autocomplete stream has been modified does Outlook save the copy back to that hidden message on the mail account’s delivery store on Outlook shutdown.

Follow the guidelines below if you want to programmatically access the autocomplete stream:

  • Interact with the autocomplete stream only while Outlook is not running. If you modify the stream while Outlook is running, Outlook will likely overwrite your changes when it shuts down.
  • Never partially modify the autocomplete stream. Always carry out the following process when updating:

                           i.          Read the whole stream into memory

                          ii.          Modify the memory structure

                         iii.          Write out the whole stream when the modifications are finished.

  • Only introduce properties to the stream that are of the supported types. The list of supported property types is as follows:
    • Static property values of the following types: PT_I2, PT_LONG, PT_R4, PT_DOUBLE, PT_BOOLEAN, PT_SYSTIME, PT_I8
    • Dynamic property values of the following types: PT_STRING8, PT_UNICODE, PT_CLSID, PT_BINARY, PT_MV_BINARY, PT_MV_STRING8, PT_MV_UNICODE

To access the PidTagRoamingBinary property, you can use MAPI or the PropertyAccessor of the Outlook object model. The binary format of the autocomplete stream in Outlook 2010 is the same as that of the .nk2 file in Outlook 2007. For details about the binary stream format, see the document Outlook 2003/2007 NK2 File Format and Developer Guidelines. Note that this document was originally written for Outlook 2007 and Outlook 2003, and in Outlook 2010, the nickname cache is no longer stored in a .nk2 file, but in the MAPI property PidTagRoamingBinary, so you should disregard discussions of the .nk2 file and refer to the part of the document starting from the section “File Visualization”.