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

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.

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

PhoneNumber Labels

The following labels can be associated with PhoneNumber elements.

Person Labels

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

PhysicalAddress Labels

The following labels can be associated with PhysicalAddress elements.

Photo Labels

The following labels can be associated with Photo elements.

Date Labels

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

Url Labels

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