How to use MAPI to manage messages in a .pst file when you are using Outlook 2003 to download messages from an IMAP server (912238)

MORE INFORMATION

Messages that are downloaded to a .pst file from an IMAP server can be in one of two states:

• Only the header is downloaded.
• Both the header and the body of the message are downloaded.

When messages are downloaded from an IMAP server to a .pst file, if you try to use MAPI to access a message in the .pst file without first unwrapping the .pst file, you may initiate synchronization with the IMAP server that will download the complete message to the .pst file.

Therefore, you must use the UnwrapNoRef function on the .pst file before you try to access messages in the .pst file. The IMsgStore interface that is returned by the UnwrapNoRef function is identical to the IMsgStore interface that is wrapped. However, when you unwrap the .pst file, you can access messages in the .pst file in the current state without triggering a download from the IMAP server.

If the QueryInterface method returns the MAPI_E_INTERFACE_NOT_SUPPORTED error, the .pst file is not wrapped.

Definitions

The following are the definitions for the UnwrapNoRef function:

#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

Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.

To use the UnwrapNoRef function, first call the QueryInterface method on the source message store to obtain the IProxyStoreObject interface. Then, call the UnwrapNoRef function to obtain the unwrapped .pst file. Note that the UnwrapNoRef function does not call the Addref method on the returned pointer.

Example

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