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
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 Programming Windows Contacts 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 CreateArrayNode). The data contained in these new properties can be enumerated by IContactProperties from other applications. For an example of this, see Programming Windows Contacts.
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 GetString, GetDate, and 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 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 |