[This is now documented here: http://msdn.microsoft.com/en-us/library/bb820960.aspx]
Using the Appropriate Interface to Manage Messages in an OST in Cached Exchange Mode
INTRODUCTION
The following article provides information when using Microsoft Collaboration Data Objects (CDO)and how to manage messages in an Offline Store (OST) while the client is in Cached Exchange mode.
MORE INFORMATION
When in cached Exchange mode, messages in the OST can be in one of two states:
Use the IID_IMessageRaw GUID when requesting an IMessage interface for a message in an OST while in cached Exchange mode. Using the IID_IMessage GUID to request an IMessage interface on a message that has only its header downloaded will force a synchronization that will attempt to download the entire message.
Using IID_IMessageRaw and IID_IMessage to request an IMessage interface will return interfaces that are identical in use. The only difference is that the IMessage interface requested with IID_IMessageRaw will return an email message as it exists in the OST, without forcing synchronization.
If OpenEntry returns the error code, MAPI_E_INTERFACE_NOT_SUPPORTED, then the message store does not support accessing the message in raw mode. In this case attempt OpenEntry again passing IID_IMessage.
Note: While cached mode is similar to remote mail headers as used in classic offline mode, the default behavior is different. Remote mail header messages are not downloaded when accessed. This GUID will not work with remote mail headers.
Definition of IID_IMESSAGE_RAW
#if !defined(INITGUID) || defined(USES_IID_IMessageRaw) DEFINE_OLEGUID(IID_IMessageRaw, 0x0002038A, 0, 0); #endif
Usage When calling OpenEntry, pass IID_IMessageRaw instead of IID_IMessage. The following code sample illustrates the usage:
HRESULT HrOpenRawMessage ( LPMDB lpMSB, ULONG cbEntryID, LPENTRYID lpEntryID, ULONG ulFlags, LPMESSAGE* lpMessage ) { ULONG ulObjType = NULL; HRESULT hRes = lpMDB->OpenEntry( cbEntryID, lpEntryID, IID_IMessageRaw, ulFlags, &ulObjType, (LPUNKNOWN*) lpMessage)); return hRes; }
[This is now documented here: http://msdn.microsoft.com/en-us/library/bb905282.aspx, http://msdn.microsoft.com/en-us/library/bb820925.aspx, http://msdn.microsoft.com/en-us/library/bb821181.aspx]
This information was also published as http://support.microsoft.com/kb/912237.
Recently the Outlook development team has agreed to document some bits and pieces about Outlook that we've never documented before. I've been charged with getting this documentation out to the development community. After publishing the information here, my next step will be to take your feedback and submit this as an article in our Knowledge Base. This information may also show up in a future release of the MSDN.
The first I'll be covering - The Contact Address Book
Topic Relating Contact Address Book entries to Contact messages, reading e-mail addresses from Contact messages, and locating Contact photos on Contact messages
Contab Outlook 2003 ships with a Contact Address Book provider, contab32.dll. This provider presents information from a user’s Contacts folder in the form of an address book so that the contacts may be used to address e-mail messages. All Contacts which have an e-mail address or fax number will be represented in the address book, with a separate listing for each e-mail address or fax number. Since a Contact may have 3 e-mail addresses and 3 fax numbers, this means each Contact may be represented by up to 6 separate entries in the address book.
The information present on a Contact Address Book entry is a subset of the information present on the underlying Contact message. The following structure can be used to determine which Contact message a particular Contact Address Book entry is derived from.
Definition
#pragma pack(4) typedef struct _contab_entryid { BYTE misc1[4]; MAPIUID misc2; ULONG misc3; ULONG misc4; ULONG misc5; // EntryID of contact in store. ULONG cbeid; BYTE abeid[1]; } CONTAB_ENTRYID, *LPCONTAB_ENTRYID; #pragma pack()
Usage The CONTAB_ENTRYID structure defines the format of the entry IDs of IMailUser objects used in the Outlook Address Book.
Entry IDs of this type could be obtained from the PR_ENTRYID column of the Outlook Address Book's contents table or from the PR_ENTRYID property on an IMailUser object opened from the Outlook Address Book.
To open the underlying Contact message, cast the Contact Address Book entry ID to this structure and then use the cbeid and abeid members as the Contact’s entry ID. For example:
HRESULT HrOpenContact( LPMAPISESSION lpSession, ULONG cbEntryID, LPENTRYID lpEntryID, ULONG ulFlags, LPMESSAGE* lpContactMessage) { ULONG ulObjType = NULL; if (sizeof(CONTAB_ENTRYID) > cbEntryID) return MAPI_E_INVALID_PARAMETER; LPCONTAB_ENTRYID lpContabEID = (LPCONTAB_ENTRYID) lpEntryID; HRESULT hRes = lpSession->OpenEntry( lpContabEID->cbeid, (LPENTRYID) lpContabEID->abeid, NULL, ulFlags, &ulObjType, (LPUNKNOWN*) lpContactMessage); return hRes; }
Contact E-Mail Addresses The only way to access the e-mail addresses on a Contact message is through named properties on the message. These properties documented here are only supported as read-only properties. We cannot support solutions which write to these properties.
Definitions
DEFINE_OLEGUID(PSETID_Address, MAKELONG(0x2000+(0x04),0x0006),0,0); #define dispidEmailAddrType 0x8082 #define dispidEmailEmailAddress 0x8083 #define dispidEmail2AddrType 0x8092 #define dispidEmail2EmailAddress 0x8093 #define dispidEmail3AddrType 0x80A2 #define dispidEmail3EmailAddress 0x80A3
Usage Use these to fill out the MAPINAMEID structure. PSETID_Adress is the lpGuid, MNID_ID is the ulKind, and the various dispids are the lID's. Then use GetIDsFromNames to get the current property IDs for these props. All of these properties are string properties. For example:
HRESULT HrGetEmail1(LPMESSAGE lpContact) { HRESULT hRes = S_OK; LPSPropTagArray lpNamedPropTags = NULL; MAPINAMEID NamedID = {0}; LPMAPINAMEID lpNamedID = &NamedID; NamedID.lpguid = (LPGUID)&PSETID_Address; NamedID.ulKind = MNID_ID; NamedID.Kind.lID = dispidEmailEmailAddress; hRes = lpContact->GetIDsFromNames( 1, &lpNamedID, NULL, &lpNamedPropTags); if (SUCCEEDED(hRes) && lpNamedPropTags) { SPropTagArray sPropTagArray; sPropTagArray.cValues = 1; sPropTagArray.aulPropTag[0] = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[0],PT_STRING8); LPSPropValue lpProps = NULL; ULONG cProps = 0; hRes = lpContact->GetProps( &sPropTagArray, NULL, &cProps, &lpProps); if (SUCCEEDED(hRes) && 1 == cProps && lpProps && PT_STRING8 == PROP_TYPE(lpProps[0].ulPropTag) && lpProps[0].Value.lpszA) { printf("Email address 1 = \"%s\"\n",lpProps[0].Value.lpszA); } MAPIFreeBuffer(lpProps); MAPIFreeBuffer(lpNamedPropTags); } return hRes; }
Contact Pictures Outlook supports a single picture for each contact. This picture is stored as an attachment on the contact’s underlying message. To determine which attachment is the picture, use the PR_ATTACHMENT_CONTACTPHOTO property. The property documented here is only supported as a read-only property. We cannot support solutions which write to this property.
#define PR_ATTACHMENT_CONTACTPHOTO PROP_TAG( PT_BOOLEAN, 0x7FFF)
Usage The PR_ATTACHMENT_CONTACTPHOTO property can be accessed as a column on the attachment table obtained through IMessage::GetAttachmentTable, or as a property on the IAttach object. If this value is true, then the attachment is the contact picture. The picture will be store as a JPEG formatted file. Use the normal MAPI methods to extract this attachment to a file.
[Update: 1/23/06 - added KB link]