MAPICDO and Long-Term Entry IDs

  • Article

When I wrote the other day about the 8211 version of the MAPICDO download, I mentioned there a new notification flag. Here’s more information on that flag.

The new flag is fnevLongTermEntryIDs:
#define fnevLongTermEntryIDs ((ULONG) 0x20000000)

This flag is not a new notification type and should not be used on its own. Instead, pass this flag in the uLEventMask parameter of IMsgStore::Advise to change the way fnevNewMail and the various fnevObject* notifications behave. Normally, when you get these notifications from the Exchange provider, the NEWMAIL_NOTIFICATION and OBJECT_NOTIFICATION structures contain Short-Term Entry IDs. With the addition of this flag, these will be Long-Term Entry IDs.

We added this flag to help with a common performance issue: MAPI clients which are tracking changes to messages will typically index their current view of messages by the Long-Term Entry ID. When they get a notification that an item has changed, they would call OpenEntry to open the item and from there request the Long-Term Entry ID so they can match the notification to the item in their index. They’d have to do this even if they don’t need any other properties from the message. These repeated OpenEntry calls can be expensive. By implementing the fnevLongTermEntryIDs flag, we’re giving them a way to avoid most of these calls.

Some notes:

  • This flag is only available in the MAPICDO download, version 6.5.8211 and above. It will not work in earlier versions of the download and will not work with Outlook’s MAPI. Attempting to use this flag on those versions of MAPI will give MAPI_E_UNKNOWN_FLAGS.
  • This flag will only work with the Exchange provider, emsmdb32.dll. It will not work with other providers, such as the PST provider, mspst32.dll.
  • This flag will only work with IMsgStore::Advise. Do not attempt to use it with other implementations of Advise.
  • There is a (very small) performance cost to this flag, as the conversion from Short-Term Entry ID to Long-Term Entry ID may require an RPC to the server. The performance cost is far less than an OpenEntry call though. If you can remove any OpenEntry calls by passing this flag, then do so.
  • A side effect of this flag: If one advise sink is registered with this flag and another is registered for the same events without the flag, both will get Long-Term Entry IDs.

Enjoy!