New Outlook Documentation Part 4 - IMAP Headers

[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]

Comments

• Anonymous
  November 25, 2005
  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:
  
  
  VOID WINAPI
  DDLUnwrapObjectEx(
  IUnknown* pUnk_p,
  LVPOID* ppUnwrapped_p,
  DWORD dwFlags_p
  );
  
  Where
  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?
  
• Anonymous
  November 26, 2005
  Amit,
  It would be better to use the documented and supported interface than rely on reversed engineered functions whose behavior you cannot rely on.
  
  Steve
• Anonymous
  January 04, 2006
  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.
• Anonymous
  January 06, 2006
  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.
• Anonymous
  February 11, 2006
  Thanks Mr Griffin,
  
  I've implemented table notifications and they're much better than store notifications.
  
  Now it works!
• Anonymous
  March 15, 2010
  Steve, it appears that Hotmail account(http) unwraps following steps above.  How do I actually differentiate between the two - httpStore and IMAPStore? Thanks!