How to use the dispidHeaderItem MAPI property to identify the state of a message that you receive in Outlook 2003 (912239)

MORE INFORMATION

When Outlook 2003 is configured to connect to an IMAP or POP3 mail server, messages are downloaded to a personal folders (.pst) file. When Outlook 2003 is configured to connect to a Microsoft Exchange Server 2003 server, you can also configure Outlook 2003 to download messages to a .pst file. Additionally, you can configure Outlook 2003 to work in Cached Exchange Mode. In Cached Exchange Mode, messages are downloaded to an offline folder (.ost) file.

When Outlook 2003 is configured to work in Cached Exchange Mode or configured to connect to an IMAP mail server, the messages that are downloaded to the .ost or .pst files on the client computer can be in one of the following states:

• The header only is downloaded
• The header and body are both downloaded

You can use the dispidHeaderItem MAPI property to identify whether the message in the .ost or .pst file is in the "header only is downloaded" or the "header and body are both downloaded" state. The dispidHeaderItem MAPI property is a PT_LONG data type and is in the PSETID_Common namespace. The dispidHeaderItem MAPI property returns a value of non-zero when the message is in the "header only is downloaded" state.

Note The dispidHeaderItem MAPI property does not apply to remote transport headers. Remote transport headers can be distinguished by the IPM.Remote message class.

The dispidHeaderitem MAPI property and PSETID_Common namespace are defined in the following code:

#define dispidHeaderItem 0x8578
DEFINE_OLEGUID(PSETID_Common, MAKELONG(0x2000+(8),0x0006),0,0);

Sample code 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. The following is an example of how the dispidHeaderItem MAPI property can be used to identify the current state of a message:

BOOL bIsHeader(LPMESSAGE lpMessage)
{
	HRESULT         hRes = S_OK;
	BOOL            bRet = false;
	ULONG	          ulVal = 0;
	LPSPropValue    lpPropVal = NULL;
	LPSPropTagArray lpNamedPropTag = NULL;
	MAPINAMEID      NamedID = {0};
	LPMAPINAMEID    lpNamedID = NULL;

	NamedID.lpguid = (LPGUID) &PSETID_Common;
	NamedID.ulKind = MNID_ID;
	NamedID.Kind.lID = dispidHeaderItem;
	lpNamedID = &NamedID;

	hRes = lpMessage->GetIDsFromNames(1, &lpNamedID, NULL, &lpNamedPropTag);

	if (lpNamedPropTag && 1 == lpNamedPropTag->cValues)
	{
		lpNamedPropTag->aulPropTag[0] = CHANGE_PROP_TYPE(lpNamedPropTag->aulPropTag[0], PT_LONG);

		//Get the value of the property.
		hRes = lpMessage->GetProps(lpNamedPropTag, 0, &ulVal, &lpPropVal);
		if (lpPropVal && 1 == ulVal && PT_LONG == PROP_TYPE(lpPropVal->ulPropTag) && lpPropVal->Value.ul)
		{
			bRet = true;
		}
	}
	
	MAPIFreeBuffer(lpPropVal);
	MAPIFreeBuffer(lpNamedPropTag);
	return bRet;
}