Share via

New Outlook Documentation Part 1 - Contact Linking

  • Article

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

Comments

  • Anonymous
    October 26, 2005
    I think there is also a way to construct EntryID of ContactsAddressBook (IABContainer) for given Contacts folder (IFolder) in message store.

    The same question about EntryID of IDistList?

    Could you please comment these?

    Sergei M. Zinovyev

  • Anonymous
    October 26, 2005
    Sergei,
    We're not planning right now on documenting either of those.
    Steve

  • Anonymous
    October 26, 2005
    Steve,

    I tried to compare 2 EntryIDs.

    EntryID1: EntryID of IContactItem:
    Length: 70 (0x00000046)
    Bytes: 0000000001721DE10010974CB63B86B288492A640700DCA67530B8BEA74586EA9FFE572E294D00000041B1950000DCA67530B8BEA74586EA9FFE572E294D000000FA6A430000

    EntryID2: EntryID of IMailUser:
    Length: 109 (0x0000006d)
    Bytes:
    00000000FE42AA0A18C71A10E8850B651C240000030000000400000000000000460000000000000001721DE10010974CB63B86B288492A640700DCA67530B8BEA74586EA9FFE572E294D00000041B1950000DCA67530B8BEA74586EA9FFE572E294D000000FA6A430000ADBAEE


    Let me analyze the second:

    BYTE misc1[4];
    00000000
    MAPIUID misc2; // 16 bytes
    FE42AA0A18C71A10E8850B651C240000
    ULONG misc3; // Always 3?
    03000000
    ULONG misc4; // Always 4?
    04000000
    ULONG misc5; // Index of address info in ContactItem: 0, 1, or 2.
    00000000
    // EntryID of contact in store, equils to EntryID1
    46000000
    0000000001721DE10010974CB63B86B288492A640700DCA67530B8BEA74586EA9FFE572E294D00000041B1950000DCA67530B8BEA74586EA9FFE572E294D000000FA6A430000
    // The last 3 bytes. (???)
    ADBAEE


    What are the last 3 bytes in EntryID of IMailUser? I cannot open IMailUser if I use EntryID without these 3 bytes.

    Sergei M. Zinovyev

  • Anonymous
    October 27, 2005
    I want information on how to import the Earthlink address book into outlook contacts and there doesn't seem to be any information on how to do this.

    It is a bit more complicated than just importing a csv file into Outlook Contacts from a csv formatted file that was exported from Earthlink. The fields do not match and even after I set up the fields to match the email addresses are not imported even though they exist in the csv file.

  • Anonymous
    October 28, 2005
    Sergei,
    The entry ID is, as noted in the cbeid field, 70 bytes. So that there may be additional information after the entry ID is not relevent. This documentation is not intended to instruct you in building Contab entry IDs - only in mapping such entry IDs back to their source contact messages.

    Charles,
    Your question is not related to the topic of this post. Perhaps you should try an Outlook related newsgroup.

    Steve

  • Anonymous
    October 31, 2005
    Steve,

    Yes, you have documented the way how to get EntryID of IMessage from EntryID of IMailUser.

    You sad "A" and I just wish to say "B". And I undestand that you did not document the way how to construct EntryID of IMailUser for EMail1(2, 3) of ContactItem.

    Sergei

  • Anonymous
    July 06, 2006
    Hi,

    I got "error LNK2001: unresolved external symbol _PSETID_Address" and "fatal error LNK1120: 1 unresolved externals" when compile this code.

    I know it is linking problem but don't know which library should be added.

    Thanks for your help.

    Huan

  • Anonymous
    July 10, 2006
    Nope - that's not a linking problem. In one of your source files you need to #define INITGUID before including initguid.h and your DEFINE_OLEGUID statement.

    BTW, this is discussed in http://support.microsoft.com/default.aspx?130869 which does apply to DEFINE_OLEGUID.

  • Anonymous
    July 13, 2006
    Thanks Stephen, I got it compiled.

    I'm also looking for documentation about using MAPI forms (such as Contact Detail, Email messages ,and so on. Do you know where to get it?

    Many thanks,

    Huan

  • Anonymous
    November 10, 2006
    Just for completeness sale, the following named property must be set to true on the message when adding a contact picture: {00062004-0000-0000-C000-000000000046}, 0x8015, PT_BOOLEAN

  • Anonymous
    July 03, 2007
    We had a customer report recently that when he tried to fetch certain properties using the Outlook Object

  • Anonymous
    December 24, 2007
    I'm using the builtin table linking to find duplicate phone numbers, thus: SELECT First, Last, Phone, 1 As Type FROM Contacts Where Phone is not null UNION SELECT First, Last,  [Mobile Phone], 2 FROM Contacts Where [Mobile Phone] is not null UNION SELECT First, Last, [Pager Phone], 3 FROM Contacts Where [Pager Phone] is not null UNION SELECT First, Last,  [Home2 Phone], 4 FROM Contacts Where [Home2 Phone] is not null UNION SELECT First, Last, [Assistant Phone Number], 5 FROM Contacts Where [Assistant Phone Number] is not null UNION SELECT First, Last, [Business Fax], 6 FROM Contacts where [Business Fax] is not null UNION SELECT First, Last,  [Home Fax], 7 FROM Contacts where [Home Fax] is not null UNION SELECT First, Last, [Other Fax], 8 FROM Contacts where [Other Fax] is not null UNION SELECT First, Last, [Telex Number], 9 FROM Contacts where [Telex Number] is not null; The problem is that I need the object's {U|GUID} to do the update query when I determine phone numbers that I want to change.  The UNION carry cannot carry the EntryID property through. Any ideas?

  • Anonymous
    December 24, 2007
    The comment has been removed