New Outlook Documentation Part 4 - IMAP Headers

Article
11/23/2005

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

[This information also published as https://support.microsoft.com/kb/912238]

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.

Topic
A mechanism to manage messages in an IMAP store.

IID_IProxyStoreObject
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.

Definition

 #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);

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

DECLARE_MAPI_INTERFACE_(IProxyStoreObject, IUnknown)
{
   BEGIN_INTERFACE
   MAPI_IUNKNOWN_METHODS(PURE)
   MAPI_IPROXYSTOREOBJECT_METHODS(PURE)
};

Usage

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 HrUnWrapMDB(LPMDB lpMDBIn, LPMDB* lppMDBOut)
{
   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:
         lpUnwrappedMDB->AddRef();
         (*lppMDBOut) = lpUnwrappedMDB;
      }
   }
   if (lpProxyObj) lpProxyObj->Release();
   return hRes;
}

[Update: Added KB link]

New Outlook Documentation Part 4 - IMAP Headers

Additional resources