How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode

How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode

This topic contains a code sample in C++ that shows how to use IID_IMessageRaw in IMsgStore::OpenEntry to obtain an IMessage interface that appropriately manages a message in an offline folders file (OST) without forcing a download of the entire message when the client is in Cached Exchange Mode.

When a client is in Cached Exchange Mode, messages in the OST can be in one of two states:

  • The entire message containing the header and the body is downloaded.
  • The message with only its header is downloaded.

When you request an IMessage interface for a message in an OST and the client is in Cached Exchange Mode, use IID_IMessageRaw. If you use IID_IMessage to request an IMessage interface, and if the message has only its header downloaded in the OST, you invoke a synchronization that attempts to download the entire message.

If you use IID_IMessageRaw or IID_IMessageGUID to request an IMessage interface, the interfaces that are returned are identical in use. The IMessage interface that was requested by using IID_IMessageRaw returns an e-mail message as it exists in the OST, and synchronization is not forced.

The following code sample shows calling the OpenEntry method, passing IID_IMessageRaw instead of IID_IMessage.

  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; }

If the OpenEntry method returns the MAPI_E_INTERFACE_NOT_SUPPORTED error code, it indicates that the message store does not support accessing the message in raw mode. In this situation, try the OpenEntry method again by passing IID_IMessage.

See Also

About MAPI Additions

Additional MAPI Constants