New Outlook Documentation Part 4 – IMAP Headers

[This is now documented here:]

[This information also published as]

Just like Cached mode has a way of accessing items in the OST without triggering a download, our IMAP provider has a mechanism for accessing items in the PST without triggering the download. In an ideal world, they’d both use the same mechanism, but nobody’s perfect.

A mechanism to manage messages in an IMAP store.

In an IMAP profile, messages in the PST can be in one of two states

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

Query for this interface to access a function, UnwrapNoRef, which unwraps the IMAP store and allows access to the underlying PST. Without unwrapping, access of a message in the IMAP store can force a synchronization that will attempt to download the entire message. Using the unwrapped store allows access to the message in its current state without triggering this download.

The IMsgStore interface returned by UnwrapNoRef is identical in use to the IMsgStore that was unwrapped. The only difference is that the unwrapped store will return messages as they exist in the PST, without forcing synchronization.

If QueryInterface returns the error MAPI_E_INTERFACE_NOT_SUPPORTED, then the store was not wrapped.


#define DEFINE_PRXGUID(_name, _l) \
DEFINE_GUID(_name, (0x29F3AB10 + _l), 0x554D, 0x11D0, 0xA9, \
   0x7C, 0x00, 0xA0, 0xC9, 0x11, 0xF5, 0x0A)

DEFINE_PRXGUID(IID_IProxyStoreObject, 0x00000000L);

MAPIMETHOD(PlaceHolder1) () IPURE; \
MAPIMETHOD(UnwrapNoRef) (LPVOID *ppvObject) IPURE; \
MAPIMETHOD(PlaceHolder2) () IPURE;

DECLARE_MAPI_INTERFACE_(IProxyStoreObject, IUnknown)


Call QueryInterface on the source message store to obtain the IProxyStoreObject interface. Then call UnwrapNoRef to obtain the unwrapped store. Note that UnwrapNoRef does not addref the returned pointer.

   HRESULT hRes = S_OK;
   IProxyStoreObject* lpProxyObj = NULL;
   LPMDB lpUnwrappedMDB = NULL;
   hRes = lpMDBIn->QueryInterface(IID_IProxyStoreObject,(void**)&lpProxyObj);
   if (SUCCEEDED(hRes) && lpProxyObj)
      hRes = lpProxyObj->UnwrapNoRef((LPVOID*)&lpUnwrappedMDB);
      if (SUCCEEDED(hRes) && lpUnwrappedMDB)
         // UnwrapNoRef doesn't addref, so we do it here:
         (*lppMDBOut) = lpUnwrappedMDB;
   if (lpProxyObj) lpProxyObj->Release();
   return hRes;

[Update: Added KB link]

Comments (6)

  1. Amit Joshi says:

    Very interesting… :) This is one of the interfaces that we have struggled with in the past. I may be wrong but I have seen msmapi create a wraper on top of pst’s wrapper. If that happens we need to remove that wrapper before the code above can get access to the underlying MDB store object. If the above scenario is right, an easier way to achieve this is using an (undocumented) API exported by MsMapi32, DDLUnwrapObjectEx as follows:



    IUnknown* pUnk_p,

    LVPOID* ppUnwrapped_p,

    DWORD dwFlags_p



    pUnk_p – Wrapped Store pointer

    ppUnwrapped_p – Unwrapped pointer to be returned

    dwFlags – bit 1: Unwrap msmapi wrapper, bit 2: Unwrap pst wrapper, bit 3: Unknown

    Simply calling this function with flags as 0x3 will unwrap the required object upto the level of an innermost store object.

    Also this function returns an AddRef’ed out pointer and doesn’t have the same quirk as the interface method UnwrapNoRef

    Makes sense?

  2. Stephen Griffin says:


    It would be better to use the documented and supported interface than rely on reversed engineered functions whose behavior you cannot rely on.


  3. Simon Audet says:

    Is there a way to get notified when Outlook finished downloading a message.

    I tought I would get notified by the AdviseSinkOnObjectModified function but this doesn’t seem to work.

  4. Stephen Griffin says:

    I assume you’re looking at the wrapped store while Outlook is downloading the message. You might see a change in the table containing the message (haven’t tested). I’ve always found table notifications more reliable than other kinds of notifications.

  5. Simon Audet says:

    Thanks Mr Griffin,

    I’ve implemented table notifications and they’re much better than store notifications.

    Now it works!

  6. Lev says:

    Steve, it appears that Hotmail account(http) unwraps following steps above.  How do I actually differentiate between the two – httpStore and IMAPStore?