Share via

Windows Contact Schema Overview

This topic defines how the contact schema is used to read and write contact properties using IContactProperties.

New applications should not use these interfaces. These interfaces exist for backward compatibility with legacy applications. These interfaces will be unavailable in the future.

This topic contains the following sections:

  • Contact Property Categories
  • Contact Property Extensibility
  • Windows Contact Schema Element Definitions
    • Standard Labels for Contact Properties

Contact Property Categories

Contact properties fit into one of two categories:

  • Single-value: This property type has a single value for any contact. Birthdays are an example; a contact has only one birthday.
  • Hierarchical: This property type has multiple values for any contact and require labeling to differentiate individual values. A phone number is an example; a contact can have one or more phone numbers (home, work, and mobile phone).

Contact Property Extensibility

Applications that use contacts may want contact data that the application-supplied schema does not provide. IContactProperties supports two approaches to extend the base contact schema:

  • Using Labels: For hierarchical properties, application-supplied contact array nodes can be differentiated by applying labels (arbitrary strings) to each node. For example, a phone number can be labeled with Voice or Pager. You can create custom labels or use one from the base schema. See Standard Labels for Contact Properties below.
    Custom labels must be created in the form of Uniform Resource Identifiers (URIs). For more information, see Adding your own Label to a Property for a code example that uses IContactProperties to set a unique label on an existing property. IContactProperties also provides methods to manipulate labels and to filter data to obtain a desired IContactPropertyCollection.
  • Contacts API programming: For single-value and hierarchical properties, an outside application can define new contact properties and array nodes (see IContactProperties::CreateArrayNode). The data contained in these new properties can be enumerated by IContactProperties from other applications. For an example of this, see Adding your own Property to a Contact.
    Note  Developers must prefix a unique namespace (in brackets) to these new contact properties to avoid conflicts.

Windows Contact Schema Element Definitions

The following elements are defined for the base schema:

Single-Value Properties

Property Value Description
CONTACTPROP_PUB_GENDER L"Gender" Choose one of L"Male", L"Female", L"Unspecified" (default)
CONTACTPROP_PUB_NOTES L"Notes" Free text content in which to write notes
CONTACTPROP_PUB_MAILER L"Mailer" The contact's e-mail program
CONTACTPROP_PUB_CREATIONDATE L"CreationDate" The date and time the contact was created in the system

Hierarchical Properties

These properties contain many values differentiated by labels. To access the heirarchical properties through IContactProperties::GetString, IContactProperties::GetDate, and IContactProperties::GetBinary you need to provide an index (1 based). For example, a parameter in the form of L"NameCollection/Name[1]/Title" returns the Title string of the first Name property in the contact.

Property Value Description
CONTACTPROP_PUB_L1_CONTACTIDS L"ContactIDCollection" A collection of ContactIDs associated with this contact
CONTACTPROP_PUB_L2_CONTACTID L"/ContactID" An entry in the collection of IDs
CONTACTPROP_PUB_L3_VALUE L"/Value" One of the unique identifiers for this contact (as a string)
CONTACTPROP_PUB_L1_NAMECOLLECTION L"NameCollection" A collection of names associated with this contact
CONTACTPROP_PUB_L2_NAME L"/Name" An entry in the collection of names
CONTACTPROP_PUB_L3_FORMATTEDNAME L"/FormattedName" The name as displayed, such as "John H. Smith III"
CONTACTPROP_PUB_L3_PHONETIC L"/Phonetic"" Name as pronounced
CONTACTPROP_PUB_L3_PREFIX L"/Prefix"" A prefix to the contact name, such as "Ms."
CONTACTPROP_PUB_L3_TITLE L"/Title" A person's title, such as "Dr."
CONTACTPROP_PUB_L3_GIVENNAME L"/GivenName" A person's first name
CONTACTPROP_PUB_L3_FAMILYNAME L"/FamilyName" A person's last name
CONTACTPROP_PUB_L3_MIDDLENAME L"/MiddleName" A person's middle name
CONTACTPROP_PUB_L3_GENERATION L"/Generation" A person's family name generation, such as "III" or "Jr."
CONTACTPROP_PUB_L3_SUFFIX L"/Suffix" A person's credentials, such as "PhD"
CONTACTPROP_PUB_L3_NICKNAME L"/NickName" A person's nickname, such as "Ace"
CONTACTPROP_PUB_L1_POSITIONCOLLECTION L"PositionCollection" Collection of positions that a contact holds
CONTACTPROP_PUB_L2_POSITION L"/Position" An entry in the collection of names
CONTACTPROP_PUB_L3_ORGANIZATION L"/Organization" The contact's organization, such as "IEEE"
CONTACTPROP_PUB_L3_COMPANY L"/Company" The contact's company, such as "Microsoft"
CONTACTPROP_PUB_L3_DEPARTMENT L"/Department" The department, such as "Accounting"
CONTACTPROP_PUB_L3_OFFICE L"/Office" The office number, such as "10/1234"
CONTACTPROP_PUB_L3_JOB_TITLE L"/JobTitle" Any job title, such as "Software Engineer"
CONTACTPROP_PUB_L3_PROFESSION L"/Profession" The line of work, such as "Plumber"
CONTACTPROP_PUB_L3_ROLE L"/Role" The role in the organization, such as "Quality Assurance"
CONTACTPROP_PUB_L1_PERSONCOLLECTION L"PersonCollection" Collection of people associated with the contact
CONTACTPROP_PUB_L2_PERSON L"/Person" Entry in the collection
CONTACTPROP_PUB_L3_FORMATTEDNAME L"/FormattedName" The person's formatted (display) name
CONTACTPROP_PUB_L3_PERSONID L"/PersonID" Unique ID for this person, which may be a ContactID from another IContact entry
CONTACTPROP_PUB_L1_DATECOLLECTION L"DateCollection" Collection of dates associated with the contact
CONTACTPROP_PUB_L2_DATE L"/Date" Entry in the collection
CONTACTPROP_PUB_L3_VALUE L"/Value" Value for this date, as a DateTime
CONTACTPROP_PUB_L1_EMAILADDRESSCOLLECTION L"EmailAddressCollection" Collection of email addresses
CONTACTPROP_PUB_L2_EMAILADDRESS L"/EmailAddress" Entry in the collection
CONTACTPROP_PUB_L3_ADDRESS L"/Address" The address, such as
CONTACTPROP_PUB_L3_TYPE L"/Type" Type of address (for example, SMTP or x509)
CONTACTPROP_PUB_L1_CERTIFICATECOLLECTION L"CertificateCollection" Collection of certificate data and thumbprints
CONTACTPROP_PUB_L2_CERTIFICATE L"/Certificate" Entry in the collection
CONTACTPROP_PUB_L3_VALUE L"/Value" Certificate value
CONTACTPROP_PUB_L3_THUMBPRINT L"/ThumbPrint" Thumbprint value
CONTACTPROP_PUB_L1_PHONENUMBERCOLLECTION L"PhoneNumberCollection" Collection of phone numbers
CONTACTPROP_PUB_L2_PHONENUMBER L"/PhoneNumber" Entry in the collection
CONTACTPROP_PUB_L3_NUMBER L"/Number" Normal number to display (as string)
CONTACTPROP_PUB_L3_ALTERNATE L"/Alternate" Alternate number (as string)
CONTACTPROP_PUB_L1_PHYSICALADDRESSCOLLECTION L"PhysicalAddressCollection" Collection of physical addresses
CONTACTPROP_PUB_L2_PHYSICALADDRESS L"/PhysicalAddress" Entry in the collection
CONTACTPROP_PUB_L3_ADDRESSLABEL L"/AddressLabel" The exact data that a mailing label contains
CONTACTPROP_PUB_L3_STREET L"/Street" Number and street
CONTACTPROP_PUB_L3_LOCALITY L"/Locality" City or urban district
CONTACTPROP_PUB_L3_REGION L"/Region" State or Province
CONTACTPROP_PUB_L3_POSTALCODE L"/PostalCode" Zip or PostalCode
CONTACTPROP_PUB_L3_COUNTRY L"/Country" The country, territory, or nation
CONTACTPROP_PUB_L3_EXTENDEDADDRESS L"/ExtendedAddress" Any extra information
CONTACTPROP_PUB_L1_IMADDRESSCOLLECTION L"IMAddressCollection" Instant Messaging Service (IM) addresses and protocols
CONTACTPROP_PUB_L2_IMADDRESSENTRY L"/IMAddress" Entry in the collection
CONTACTPROP_PUB_L3_VALUE L"/Value" The identifing data (for example,
CONTACTPROP_PUB_L3_PROTOCOL L"/Protocol" The protocol as a string (for example, Messenger Protocol)
CONTACTPROP_PUB_L1_URLCOLLECTION L"UrlCollection" Collection of URLs associated with this contact
CONTACTPROP_PUB_L2_URL L"/Url" An entry in the collection of url
CONTACTPROP_PUB_L3_VALUE L"/Value" The actual URL data (as a string)
CONTACTPROP_PUB_L1_PHOTOCOLLECTION L"PhotoCollection" Collection of images associated with this contact
CONTACTPROP_PUB_L2_PHOTO L"/Photo" An entry in the collection of photos
CONTACTPROP_PUB_L3_VALUE L"/Value" Image that represents the contact (binary with MIME type)
CONTACTPROP_PUB_L3_URL L"/Url" A URL for retrieving the image (as a string)

Standard Labels for Contact Properties

These labels differentiate second level (L2) entries. For example, a company address is created by labelling a CONTACTPROP_PUB_L2_PHYSICALADDRESS property as Business.

Common Contact Labels

Label Value Description
CONTACTLABEL_PUB_PREFERRED L"Preferred" Note: many entries in a set may have this "Preferred" label set.
CONTACTLABEL_PUB_PERSONAL L"Personal" Home-related data
CONTACTLABEL_PUB_BUSINESS L"Business" Work-related data
CONTACTLABEL_PUB_OTHER L"Other" Some other label (but not a URI substitute for a label)

PhoneNumber Labels

The following labels can be associated with PhoneNumber elements.

Label Value Description
CONTACTLABEL_PUB_VOICE L"Voice" A number that supports voice conversation
CONTACTLABEL_PUB_MOBILE L"Mobile" A mobile phone number
CONTACTLABEL_PUB_CELLULAR L"Cellular" A cell phone support
CONTACTLABEL_PUB_CAR L"Car" A number for travel
CONTACTLABEL_PUB_PAGER L"Pager" A pager number
CONTACTLABEL_PUB_FAX L"Fax" A fax machine number
CONTACTLABEL_PUB_VIDEO L"Video" number supports video conversation
CONTACTLABEL_PUB_MODEM L"Modem" A number for modem connection
CONTACTLABEL_PUB_BBS L"BBS" A number for BBS connection

Person Labels

The following labels can be associated with Person elements. Some of these labels are specific to the Microsoft Windows Address Book (WAB).

Label Value Description
CONTACTLABEL_PUB_AGENT L"Agent" This person is allowed to work on behalf of the contact
CONTACTLABEL_WAB_SPOUSE L"wab:Spouse" The contact's spouse
CONTACTLABEL_WAB_CHILD L"wab:Child" A child of the contact
CONTACTLABEL_WAB_MANAGER L"wab:Manager" The contact's manager
CONTACTLABEL_WAB_ASSISTANT L"wab:Assistant" The contact's personal assistant

PhysicalAddress Labels

The following labels can be associated with PhysicalAddress elements.

Label Value Description
CONTACTLABEL_PUB_DOMESTIC L"Domestic" A domestic mailing address
CONTACTLABEL_PUB_INTERNATIONAL L"International" An international mailing address
CONTACTLABEL_PUB_POSTAL L"Postal" A mailing address which accepts incoming mail
CONTACTLABEL_PUB_PARCEL L"Parcel" A mailing address that accepts packages

Photo Labels

The following labels can be associated with Photo elements.

Label Value Description
CONTACTLABEL_PUB_USERTILE L"UserTile" An image used to represent the contact
CONTACTLABEL_PUB_LOGO L"Logo" A logo (for example, to represent the contact's organization)

Date Labels

The following labels can be associated with Date elements. These labels are specific to WAB.

Label Value Description
CONTACTLABEL_WAB_BIRTHDAY L"wab:Birthday" The contact's birth date
CONTACTLABEL_WAB_ANNIVERSARY L"wab:Anniversary" A date of an important event

Url Labels

The following labels can be associated with Url elements. These labels are specific to WAB.

Label Value Description
CONTACTLABEL_WAB_SOCIALNETWORK L"wab:SocialNetwork" A link to an online community
CONTACTLABEL_WAB_SCHOOL L"wab:School" The site of an educational institution
CONTACTLABEL_WAB_WISHLIST L"wab:WishList" A page of bookmarked items