New Outlook Documentation Part 2 - Cached Mode Headers

  • Article

[This is now documented here: https://msdn.microsoft.com/en-us/library/bb820960.aspx]

Using the Appropriate Interface to Manage Messages in an OST in Cached Exchange Mode

INTRODUCTION

The following article provides information when using Microsoft Collaboration Data Objects (CDO)and how to manage messages in an Offline Store (OST) while the client is in Cached Exchange mode.

MORE INFORMATION

When in cached Exchange mode, messages in the OST can be in one of two states:

  • A message in its entirety - with the header and body.
  • A message with only its header downloaded.

Use the IID_IMessageRaw GUID when requesting an IMessage interface for a message in an OST while in cached Exchange mode. Using the IID_IMessage GUID to request an IMessage interface on a message that has only its header downloaded will force a synchronization that will attempt to download the entire message.

Using IID_IMessageRaw and IID_IMessage to request an IMessage interface will return interfaces that are identical in use. The only difference is that the IMessage interface requested with IID_IMessageRaw will return an email message as it exists in the OST, without forcing synchronization.

If OpenEntry returns the error code, MAPI_E_INTERFACE_NOT_SUPPORTED, then the message store does not support accessing the message in raw mode. In this case attempt OpenEntry again passing IID_IMessage.

Note: While cached mode is similar to remote mail headers as used in classic offline mode, the default behavior is different. Remote mail header messages are not downloaded when accessed. This GUID will not work with remote mail headers.

Definition of IID_IMESSAGE_RAW

 #if !defined(INITGUID) || defined(USES_IID_IMessageRaw)
DEFINE_OLEGUID(IID_IMessageRaw, 0x0002038A, 0, 0);
#endif

 

Usage

When calling OpenEntry, pass IID_IMessageRaw instead of IID_IMessage. The following code sample illustrates the usage:

 HRESULT HrOpenRawMessage
(
   LPMDB lpMSB, 
   ULONG cbEntryID, 
   LPENTRYID lpEntryID, 
   ULONG ulFlags, 
   LPMESSAGE* lpMessage
)
{
   ULONG ulObjType = NULL;

   HRESULT hRes = lpMDB->OpenEntry(
      cbEntryID,
      lpEntryID,
      IID_IMessageRaw,
      ulFlags,
      &ulObjType,
      (LPUNKNOWN*) lpMessage));

   return hRes;
}