New Outlook Documentation Part 1 - Contact Linking

[This is now documented here: https://msdn.microsoft.com/en-us/library/bb905282.aspx, https://msdn.microsoft.com/en-us/library/bb820925.aspx, https://msdn.microsoft.com/en-us/library/bb821181.aspx]

This information was also published as https://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.

Definition

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