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_PROGID | L"ProgID" | The ProgID of mailer |
| 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 example@microsoft.com | ||
| 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_POBOX | L"/POBox" | Any POBox number | ||
| 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, username@microsoft.com) | ||
| 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_PCS | L"PCS" | PCS support |
| 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_TTY | L"TTY" | A tty machine |
| 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 |
| CONTACTLABEL_PUB_ISDN | L"ISDN" | A number for ISDN |
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 |