W3C

Contacts API

W3C Working Draft 09 December 2010

This version:
http://www.w3.org/TR/2010/WD-contacts-api-20101209/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/contacts/
Previous version:
http://www.w3.org/TR/2010/WD-contacts-api-20100817/
Editor:
Richard Tibbett, Opera Software ASA

Abstract

The Contacts API defines the high-level interfaces required to provide read access to a user's unified address book.

Methods to manipulate a user's unified address book, to add and remove contact information, are being developed in an accompanying specification [CONTACTS-WRITER-API].

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like to get feedback.

This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

2. Introduction

This section is non-normative.

Every operating system and a large number of web-based service providers have different ways of representing address book information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being stored across a user's address book providers.

Providing address book information to these service providers means handing over all of your data and trusting these providers with the security and privacy of storing and sharing of your information. When sharing this data with third parties users are, more often than not, required to hand over access to their whole address book. Users are implicitly required to trust third parties with all of their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an application can fulfill its purpose.

This specification defines the concept of a user's unified address book - where address book data may be sourced from a plurality of sources - both online and locally. This specification then defines the interfaces on which third party applications can access a user's unified address book, with explicit user permission and filtering. The focus of this data sharing is on making the user aware of the data that they will share and putting them at the center of the data sharing process; free to select both the extent to which they share their address book information and the ability to restrict which pieces of information related to which contact gets shared.

A conforming implementation is required to implement all fields defined in this specification.

The following code illustrates how to obtain contact information from a user's address book:

function successContactFindCallback(contacts) {
    // do something with resulting contact objects
    for (var i in contacts) alert(contacts[i].displayName);
    // ...
}

function generalErrorCB(error) {
    // do something with resulting errors
    alert(error.code);
    // ...
}

// Perform an address book search. Obtain the 'name' and 'emails' properties 
// and initially filter the list to Contact records containing 'Bob':
navigator.service.contacts.find(['name', 'emails'],
                                successContactFindCallback, 
                                generalErrorCB,
                                {filter: 'Bob'}
                               );
// ..is equivalent to: navigator.service.contacts(/* parameters */)

2.1 Terminology

The terms document base URL, browsing context, event handler attributes, event handler event type, task, task source and task queues are defined by the HTML5 specification [HTML5].

The task source used by this specification is the PendingOp task source.

PendingOp needs updating in [CORE-DEVICE] to show that it is a valid task source.

To dispatch a success event means that an event with the name success, which does not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactFindCB object.

To dispatch an error event means that an event with the name error, which does not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactErrorCB object.

3. Security and Privacy Considerations

The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made to this API to reflect requirements or support for privacy-related functionality.

The API defined in this specification can be used to find contact information from a user's address book(s). This discloses information related to a user's contacts such as their phone number(s), email address(es) and other personally identifying information. The distribution of this information could potentially compromise the user's privacy, or the user’s contacts privacy. A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that no contact information is retrievable without the user's express permission.

3.1 Privacy considerations for implementors of the Contacts API

A user agent must not retrieve contact information to Web sites without the express permission of the user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface must include the document base URL. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context is navigated to another URL) must be revocable and a user agent must respect revoked permissions.

Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, the implementation must seek the user's express permission if and when any additional find function is called on this API.

A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web browser will present a user interface when a Web site performs an address book request, a Widget [WIDGETS] runtime may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorize the retrieval of contact information.

3.2 Privacy considerations for recipients of contact information

This section is non-normative.

Web sites owners that retrieve contacts information using this API are denoted as recipients below.

Recipients should only request contact information when necessary, and only use the contact information for the task for which it was provided to them.

Recipients should dispose of contact information once that task is completed, unless expressly permitted to retain it by the user. Recipients should also take measures to protect this information against unauthorized access. If contact information is stored, users should be allowed to update and delete this information.

The recipient of contact information should not retransmit the contact information without the user's express permission. Care should be taken when retransmitting and use of encryption is encouraged.

Recipients should clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure should include an explanation of any exceptions to the guidelines listed above.

3.3 Additional implementation considerations

This section is non-normative.

Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might simply change their minds.

Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of permissions.

4. API Description

4.1 ServiceContacts interface

The ServiceContacts interface is exposed on the navigator.service object, as defined in [CORE-DEVICE].

Service implements ServiceContacts;
 
[NoInterfaceObject]
interface ServiceContacts {
    readonly attribute Contacts contacts;
};

4.1.1 Attributes

contacts of type Contacts, readonly
The root node from which the contacts functionality can be accessed.
No exceptions.

4.2 Contacts interface

The Contacts interface exposes a database collecting contacts information that may be retrieved.

Multiple contact groups can be represented within this unified address book by specifying consistent categories value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the required categories value(s) via the Contacts find() function.

[NoInterfaceObject]
interface Contacts {
    caller PendingOp find (in DOMString[] fields, in ContactFindCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
};

4.2.1 Methods

find

Find contacts in the address book according to the find contacts process detailed below.

This method takes two, three or four arguments. When called, it immediately returns a PendingOp object, as defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows:

  1. If there are any tasks from the PendingOp task source in one of the task queues (i.e. an existing find() operation is still pending a response), and the current method was invoked with a non-null errorCB argument, dispatch an error event with a PENDING_OPERATION_ERROR code value.
  2. Search for contacts in the address book according to the rules defined in Contact Search Processing.
  3. If the attempt was successful, dispatch a success event. If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must dispatch an error event with the code attribute set according to the type of failure that has occurred.
ParameterTypeNullableOptionalDescription
fieldsDOMString[] The search qualifier.
successCBContactFindCB Function to call when the asynchronous operation completes
errorCBContactErrorCB Function to call when the asynchronous operation fails.
optionsContactFindOptions The options to apply to the output of this method.
No exceptions.
Return type: caller PendingOp

4.3 Contact interface

The attributes provided in this interface are under review and are likely to change as the recommendation progresses.

The Contact interface captures the properties of a contact object.

All Contact objects must include all attributes supported by the implementation, regardless of whether these attributes have been assigned a non-null value or a null value. If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute must still be present in the resulting Contact object and must have a value of null.

Additional attributes may be included according to the provisions detailed in Extended Contact Properties and Parameters. If an extended attribute is supported by the current implementation and has not been assigned a value by the user and/or implementation, then this extended attribute must still be present in the resulting Contact object and must have a value of null.

[NoInterfaceObject]
interface Contact {
    readonly attribute DOMString             id;
             attribute DOMString             displayName;
             attribute ContactName           name;
             attribute DOMString             nickname;
             attribute ContactField[]        phoneNumbers;
             attribute ContactField[]        emails;
             attribute ContactAddress[]      addresses;
             attribute ContactField[]        ims;
             attribute ContactOrganization[] organizations;
             attribute Date                  revision;
             attribute Date                  birthday;
             attribute DOMString             gender;
             attribute DOMString             note;
             attribute ContactField[]        photos;
             attribute DOMString[]           categories;
             attribute ContactField[]        urls;
             attribute DOMString             timezone;
};

4.3.1 Attributes

addresses of type array of ContactAddress

This attribute represents one or more physical addresses associated with this Contact.

No exceptions.
birthday of type Date

This attribute contains birthday of this Contact.

The year value may be set to 0000 when the age of the Contact is private or the year is not available.

No exceptions.
categories of type array of DOMString

This attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favorite".

No exceptions.
displayName of type DOMString

This attribute contains the display name of this Contact which is suitable for display to the end-users.

Each Contact must include either a displayName or the name attribute.

No exceptions.
emails of type array of ContactField

This attribute represents one or more email addresses associated with this Contact.

No exceptions.
gender of type DOMString

This attribute contains the gender of this Contact. This attribute should have one of the following values:

male, female, undisclosed

This attribute may return a different value if it is not covered by one of these values.

No exceptions.
id of type DOMString, readonly

A globally unique identifier for the given Contact object. Each Contact must include a non-empty id value.

An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an Address Book.

No exceptions.
ims of type array of ContactField

This attribute represents one or more instant messaging identifiers associated with this Contact.

No exceptions.
name of type ContactName

This attribute represents the full name of this Contact indicated by the name components associated with the ContactName object.

No exceptions.
nickname of type DOMString

This attribute contains the nickname (or a casual name) for this Contact.

No exceptions.
note of type DOMString

This attribute contains the personal notes (free-text) for this Contact that is managed by the user of the Address Book.

This field may contain newlines (\n).

No exceptions.
organizations of type array of ContactOrganization

This attribute represents one or more organizations associated with this Contact.

No exceptions.
phoneNumbers of type array of ContactField

This attribute represents one or more phone numbers associated with this Contact.

No exceptions.
photos of type array of ContactField

This attribute represents one or more photos (that may be displayed) associated with this Contact.

The photos must be specified in the value attribute of the ContactField object either by using a URL (representing an actual image file and not a web page pointing to that image file) or base64 encoded string representing the image data.

Service Providers may return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists.

This attribute should not be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.

No exceptions.
revision of type Date

This atttribute contains the timestamp information associated with this Contact, which represents the last known modified time. If no modified time exists, then this object contains the timestamp of when the object was created.

No exceptions.
timezone of type DOMString

The value contains the time zone of this Contact as an offset from UTC.

The value must be specified as a positive or negative difference from the UTC in units of hours and minutes (i.e. +hh:mm). Example, by specifying +05:30 indicates the Contact is associated with a current time zone of GMT+05:30.

This value may change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.

No exceptions.
urls of type array of ContactField

This attribute represents one or more web resources (i.e. URLs) associated with this Contact e.g. personal web page, blog.

The web resources must be specified by the value attribute of the ContactField object using a URL.

In addition to the standard values for type, this field also defines the additional type values:

blog, profile
No exceptions.

4.4 ContactName interface

The ContactName interface describes a contact's name.

[NoInterfaceObject]
interface ContactName {
    attribute DOMString formatted;
    attribute DOMString familyName;
    attribute DOMString givenName;
    attribute DOMString middleName;
    attribute DOMString honorificPrefix;
    attribute DOMString honorificSuffix;
};

4.4.1 Attributes

familyName of type DOMString

This attribute contains the family name (also referred to as the last name) of this Contact.

No exceptions.
formatted of type DOMString

This attribute contains the full name, including all the individual components such as givenName, middleName, familyName, prefix, suffix as appropriate, and formatted for display (e.g. Mr. Joe Smith Jr).

No exceptions.
givenName of type DOMString

This attribute contains the given name (also referred to as the first name) of this Contact.

No exceptions.
honorificPrefix of type DOMString

This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr. Dr. Ms. Mrs.,

No exceptions.
honorificSuffix of type DOMString

This attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr.

No exceptions.
middleName of type DOMString

This attribute contains the middle name of this Contact.

No exceptions.

4.5 ContactField interface

The ContactField interface is a reusable component that is used to support contact fields within the Contact interface.

[NoInterfaceObject]
interface ContactField {
    attribute DOMString type;
    attribute DOMString value;
    attribute boolean   pref;
};

4.5.1 Attributes

pref of type boolean

This attribute indicates whether this instance of the ContactField is the preferred, or primary, value for the contact property this ContactField is representing in the Contact interface.

No exceptions.
type of type DOMString

This attribute contains the type information for this ContactField and is subject to the contact property this ContactField is representing in the Contact interface. For example, if the ContactField is representing a phoneNumber property, the type attribute is set to home, mobile, and if the Contact Field is representing ims property, the type attribute is set to yahoo, gtalk, bbm, etc.

No exceptions.
value of type DOMString

This attribute contains the value for this ContactField and is subject to the contact property this ContactField is representing in the Contact interface. For example, if the ContactField is representing an email, the value attribute is set to JoeSmith@example.com, and if the ContactField is representing a url, the value attribute is set to http://www.example.org/joesmith, etc.

No exceptions.

4.6 ContactAddress interface

The ContactAddress interface is a reusable component that is used to support contact addresses within the Contact interface.

[NoInterfaceObject]
interface ContactAddress {
    attribute DOMString formatted;
    attribute DOMString streetAddress;
    attribute DOMString locality;
    attribute DOMString region;
    attribute DOMString postalCode;
    attribute DOMString country;
};

4.6.1 Attributes

country of type DOMString

This attribute contains the country name corresponding to this ContactAddress.

No exceptions.
formatted of type DOMString

This attribute contains the full physical address including street, locality, region, postalCode, and country as appropriate, and formatted for display.

No exceptions.
locality of type DOMString

This attribute contains the locality (or city) name corresponding to this ContactAddress.

No exceptions.
postalCode of type DOMString

This attribute contains the postal code (or zip) corresponding to this ContactAddress.

No exceptions.
region of type DOMString

This attribute contains the region (or state/province) name corresponding to this ContactAddress.

No exceptions.
streetAddress of type DOMString

This attribute contains the street address corresponding to this ContactAddress.

No exceptions.

4.7 ContactOrganization interface

The ContactOrganization interface is a reusable component that is used to support contact organizations within the Contact interface.

[NoInterfaceObject]
interface ContactOrganization {
    attribute DOMString name;
    attribute DOMString department;
    attribute DOMString title;
};

4.7.1 Attributes

department of type DOMString

This attribute contains the Job Title information of the Contact associated with this Organization.

No exceptions.
name of type DOMString

This attribute contains the name of the Organization and must be assigned a non-null value.

No exceptions.
title of type DOMString

This attribute contains the department information of the Organization associated with this Contact.

No exceptions.

4.8 ContactFindOptions interface

The ContactFindOptions interface describes the options that can be applied to contact searching. When a ContactFindOptions parameter is provided to the Contacts find() operation, it should be processed according to the provisions detailed in Options Processing.

[NoInterfaceObject]
interface ContactFindOptions {
    attribute DOMString? filter;
    attribute boolean?   multiple;
    attribute Date?      updatedSince;
};

4.8.1 Attributes

filter of type DOMString, nullable
A DOMString-based search filter with which to search and initially filter the Contacts database.
No exceptions.
multiple of type boolean, nullable
A boolean value to indicate whether multiple Contact objects are returnable as part of the associated Contacts find() operation.

By default this option is set to true.

No exceptions.
updatedSince of type Date, nullable

Return only contact records that have been updated on or after the given time, specified as an ECMAScript Date object.

This filter is applied to the revision field as defined in Contact.

No exceptions.

4.9 ContactFindCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindCB : PendingOp {
    void onsuccess (in Contact[] contactObjs);
};

4.9.1 Methods

onsuccess
ParameterTypeNullableOptionalDescription
contactObjsContact[] The Contact objects resulting from the given Contacts find() method. Contacts find()
No exceptions.
Return type: void

4.9.2 Event Handler Attributes

The following is the event handler attribute (and its corresponding event handler event type) that must be supported as a DOM attribute by the ContactFindCB object.

event handler attribute event handler event type
onsuccess success

4.10 ContactErrorCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactErrorCB : PendingOp {
    void onerror (in ContactError error);
};

4.10.1 Methods

onerror
ParameterTypeNullableOptionalDescription
errorContactError The Contact API related error object.
No exceptions.
Return type: void

4.10.2 Event Handler Attributes

The following is the event handler attribute (and its corresponding event handler event type) that must be supported as a DOM attribute by the ContactErrorCB object.

event handler attribute event handler event type
onerror error

4.11 ContactError interface

The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API.

[NoInterfaceObject]
interface ContactError {
    const unsigned short UNKNOWN_ERROR = 0;
    const unsigned short INVALID_ARGUMENT_ERROR = 1;
    const unsigned short TIMEOUT_ERROR = 2;
    const unsigned short PENDING_OPERATION_ERROR = 3;
    const unsigned short IO_ERROR = 4;
    const unsigned short NOT_SUPPORTED_ERROR = 5;
    const unsigned short PERMISSION_DENIED_ERROR = 20;
    readonly attribute unsigned short code;
};

4.11.1 Attributes

code of type unsigned short, readonly
An error code assigned by an implementation when an error has occurred in Contacts API processing.
No exceptions.

4.11.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
An invalid parameter was provided when the requested method was invoked.
IO_ERROR of type unsigned short
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
NOT_SUPPORTED_ERROR of type unsigned short
The requested method is not supported by the current implementation.
PENDING_OPERATION_ERROR of type unsigned short
If the user agent is currently waiting for a callback on a current find() operation, as defined in this specification.
PERMISSION_DENIED_ERROR of type unsigned short
Access to the requested method was denied at the implementation or by the user.
TIMEOUT_ERROR of type unsigned short
The requested method timed out before it could be completed.
UNKNOWN_ERROR of type unsigned short
An unknown error occurred.

5. Contact Search Processing

The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database.

5.1 Search Qualifiers

The search qualifier provides an application with a way to request the specific subset of Contact properties it wishes to obtain in any resulting successful callback. The search qualifier is deployed to minimize the data that needs to be shared with an application in order to let that application fulfill its function on behalf of the user. The search qualifier is included within a Contacts find() operation as the filter parameter.

A search qualifier must be specified from a requesting application as a part of any Contacts find() operation.

If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any Contact properties within any resulting Contact object(s).

In the case that the search qualifier provided is of non-zero-length then the current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s).

If a provided search qualifier element (filter[x]) does not match a Contact attribute, filter[x] should be ignored when executing the current Contacts find() operation.

5.1.1 Advanced Search Qualifiers

We call composed attributes Contact attributes of types object, sequence, array or any which contain information only available only through child attributes of that object.

A requesting application must be able to request both the full composed Contact attribute and also be able to request individual parts of a composed Contact attribute in the search qualifier provided to a Contacts find() operation.

For example, the name attribute of a Contact object is defined to be of composed type ContactName. Therefore, a requesting application may request either the full composed attribute (i.e. name) or specific individual attributes of this composed attribute (i.e. name.formatted, name.familyName, name.givenName, name.middleName, name.honorificPrefix, name.honorificSuffix) as part of a Contacts find() operation's search qualifier.

In the case that a composed Contact attribute is defined as a sequence or array of composed objects, specific individual attributes can be referenced by using the composed attribute name, a dot (.) character and the individual attribute to be retrieved.

For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request individual attributes of this composed attribute an application would request e.g. addresses.locality, addresses.region, etc.

The following Contact search is initiated:

 
   navigator.service.contacts.find(['emails.value', 'name', 'friends'],
                                   function(contacts) { 
                                      for(i in contacts) {
                                         for(j in contacts[i].emails)
                                            alert(contacts[i].emails[j]);
                                      }
                                   });

The above example logically implies:

  1. Return only the valid Contact attributes requested in the provided search qualifier (name, emails.value - friends is not a valid Contact attribute so ignore this element).

5.2 Options Processing

5.2.1 Search Cardinality

By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindCB callback function.

If a ContactFindOptions object is provided to the Contacts find() operation and its multiple attribute is set to true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in the ContactFindCB callback function.

5.2.2 Search Filters

A search filter may be specified from a requesting web application to initially filter the Contacts database to a more specific set of Contact objects in which it is interested. The search filter is included as the filter attribute of the ContactFindOptions object provided to a Contacts find() operation.

A search filter is used to search Contact attributes within the Contacts database and represents the logical union, or , of provided values that are matched therein.

All contact searching must apply a loose-matching policy to the search filter provided. If an attribute being searched in a Contact object, stored within the Contacts database, is a partial value match of the input filter value, that Contact object must be returned as part of the resulting ContactFindCB.

A conforming implementation must only allow the provided search filter to be applied to fields requested in the provided search qualifier. The id attribute must always be implicitly searchable from any requesting web application regardless of whether it has been included as part of any provided search qualifier. For example, if the given search qualifier contains 'name' and 'displayName', then the rules for processing search filters should only be applied to all sub-fields of the name attribute (i.e. name.formatted, name.firstName, name.givenName, name.middleName, name.honorificPrefix, name.honorificSuffix), the displayName attribute and the id attribute.

A partial value match refers to both syntactic and semantic partial matching of an input filter value with a corresponding value in the address book and denotes that a corresponding match was found in the address book that begins with, contains or ends with the value of the input filter value, or any variation thereof.

Comparing two strings in a compatibility caseless manner means using the Unicode compatibility caseless match operation to compare the two strings. [UNICODE]

A partial value match must use the compatibility caseless manner in which to match against corresponding values in the Contacts database.

 

The rules for processing search filters is defined below and is always provided with a filter parameter, representing the filter attribute of the ContactFindOptions parameter provided within the current Contacts find() operation.

 
Let contactsets be initially the set of all known contacts in the Contacts database.

Let contactsresult be initially an empty Array object.

If filter is a DOMString object
  1. Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5.
  2. Let partialMatchFound be the result of applying the partial matching algorithm, providing filter and contactset as inputs.
  3. If partialMatchFound is true, add contactset to contactsresult.
  4. Go to step 1.
  5. Return contactsresult.
If filter is another native object type

Return contactsets.

 

The partial matching algorithm is defined below and is always provided with a filter parameter, representing the input string to compare; and a contactset parameter, representing an individual Contact object:

 
Let hasPartialMatch be initially set to false.
If contactset is an Object object
  1. Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5.
  2. Let hasPartialMatch be the boolean result for the comparison of filter with elementvalue in a compatibility caseless manner and with a partial value match policy applied to both sides of the comparison operation.
  3. If hasPartialMatch is true, go to step 5.
  4. Go to step 1.
  5. Return hasPartialMatch.
If contactset is another native object type

Return false.

The following Contact search is initiated:

      navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
                                      function(contacts) { 
                                         for(x in contacts) alert(contacts[x].name); 
                                      },
                                      {
                                        filter: 'Robert'
                                      });
     

The above example logically implies:

  1. Using ECMA-262 3rd Edition regular expression syntax and pseudo-code, the search filter provided can be represented as:
    ( name.formatted = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i ) 
    ∪ ( emails.value = /∧.*Robert.*$/i ) ∪ ( name.familyName = /∧.*Robert.*$/i ) 
    ∪ ( name.givenName = /∧.*Robert.*$/i )  ∪ ( name.middleName = /∧.*Robert.*$/i )
    ∪ ( addresses.country = /∧.*Robert.*$/i ) ∪ ( addresses.locality = /∧.*Robert.*$/i )  
    ∪ ( phoneNumbers.type = /∧.*Robert.*$/i ) ∪ ( emails.type = /∧.*Robert.*$/i )
    ∪ ( id = /∧.*Robert.*$/i )
    

    All searches are case-insensitive and apply a loose-matching policy as defined in Search Filters.

    As noted in Search Filters, the id attribute is implicitly appended along with any search filter attributes provided, regardless of whether it was provided as a search qualifier from the requesting application.

  2. Return only the valid Contact properties requested in the provided search qualifier (name, addresses.locality, addresses.country, phoneNumbers, emails) and only for the Contact objects returned from the rules for processing search filters with the search filter derived in step 1 provided as the filter input parameter.

6. Extended Contact Properties and Parameters

The properties and parameters defined on the Contact interface may be extended by implementors of this specification.

Non-standard, private properties and parameters should have a prefixed name starting with X (U+0058 LATIN CAPTIAL LETTER X) or use a vendor-specific prefix. Extended properties and parameters can be defined bilaterally between user agents without outside registration or standardization.

It is recommended that authors define both a formal vCard grammar [RFC2426] and a WebIDL grammar [WEBIDL] for their proposed extension to ensure interoperability between vCard databases and other non-standard Contact databases and formats. It is also recommended that authors provide documentation of their extension properties and parameters within the public domain.

A new parameter is required by Company X to provide information related to a user's accounts registered across different networks and services.

The [WEBIDL] syntax for this parameter is defined as follows:

Contact implements ContactExtended;
 
[NoInterfaceObject]
interface ContactExtended {
    attribute ContactAccount[] Xaccounts;
};

Attributes

Xaccounts of type array of ContactAccount
One or more user accounts. See [[POCO-SCHEMA] Section 7.2.2. accounts].
No exceptions.
[NoInterfaceObject]
interface ContactAccount {
    attribute DOMString domain;
    attribute DOMString username;
    attribute DOMString userid;
};

Attributes

domain of type DOMString

See [[POCO-SCHEMA] Section 7.6. domain].

No exceptions.
userid of type DOMString

See [[POCO-SCHEMA] Section 7.6. userid].

No exceptions.
username of type DOMString

See [[POCO-SCHEMA] Section 7.6. username].

No exceptions.

The corresponding vCard [RFC2426] notation for this parameter is defined as follows:

   The following ABNF grammar extends the grammar found in [RFC2426] (Section 4).
   
   X-ACCOUNT
   
   Purpose:  To specify the components of the accounts for the vCard 
      object.

   Value type:  A single structured text value, separated by the SEMI-
      COLON character (ASCII decimal 59).

   Cardinality:  (0,n)

   Special notes:  The structured type value consists of a sequence of
      account components.  The component values must be specified in
      their corresponding position.  The structured type value
      corresponds, in sequence, to the domain; the username; the userid.
      When a component value is missing, the associated component 
      separator must still be specified.    

      The text components are separated by the SEMI-COLON character
      (ASCII decimal 59).
      
   ABNF:
   
     X-ACCOUNT-param = ; no parameter allowed
     X-ACCOUNT-value = list-component 3(";" list-component)

This parameter will be used within the Contacts API as follows:

   var contact = ...; // ...obtain individual contact object
   for(var i in contact.Xaccounts) {
      alert(contact.Xaccounts[i].domain);   // thesocialnetwork.com
      alert(contact.Xaccounts[i].username); // null
      alert(contact.Xaccounts[i].userid);   // 344aesq2
   }            

This parameter will be used within the vCard format [RFC2426]] as follows:

   X-ACCOUNT;thesocialnetwork.com;;344aesq2

A. API Invocation via DOM Events

This section is non-normative.

The API contained in this document can be invoked either programmatically (for example, inline within a general script) or resulting from the interaction of a user.

The interaction of a user is when a user invokes the API from an HTMLElement [HTML5] within the current browsing context via a valid auto-invocation event.

A valid auto-invocation event includes any of the following event types, as defined in [DOM-LEVEL-3-EVENTS]:

The find() method on Contacts should, if the method was invoked by an interaction of a user (as opposed to having been created and executed in general script), display the Contact Picker directly.

B. User Interaction Guidelines

This section is non-normative.

This specification is primarily intended to provide the user with the ability to view and control the contact information that may be shared from their unified address book. This annex provides some examples of a conformant user experience that this specification enables.

B.1 Accessing Contact Information - Example #1

A website requests access to a user's address book with the following code:

 <script type="text/javascript">
 
function successContactFindCallback(contacts) {
    // do something with resulting contact objects
    for (var i in contacts) alert(contacts[i].name);
    // ...
}

function generalErrorCB(error) {
    // do something with resulting errors
    alert(error.code);
    // ...
}

// Perform an address book search. Obtain the 'name' and 'emails' properties 
// and initially filter the list to Contact records containing 'Bob':
navigator.service.contacts.find(['name', 'emails'],
                                successContactFindCallback, 
                                generalErrorCB,
                                {filter: 'Bob'}
                               );
                               
</script>

As a result of executing this code, the user agent may provide a non-blocking contact search notification as follows:

Contact Search Notification
(View as PNG)

If an additional find() operation is called by the current web application before the user has clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a non-null errorCB parameter.

If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.

If the user clicks 'Select', the user agent may provide a contact picker, utilizing all of the parameters provided in the find() operation as follows:

Contact Picker
(View as PNG)

In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.

If an additional find() operation is called by the current web application before the user has clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a non-null errorCB parameter.

If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.

If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with the contact information selected by the user provided as the only parameter.

Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke permissions to web applications at a later date.

B.2 Accessing Contact Information - Example #2

A website requests access to a user's address book with the following code:

<input type="button" value="Share Contacts" onclick="getContacts()" />
 
<script type="text/javascript">
  function successContactFindCallback(contacts) {
    // do something with resulting contact objects
    for (var i in contacts) alert(contacts[i].name);
    // ...
  }

  function generalErrorCB(error) {
    // do something with resulting errors
    alert(error.code);
    // ...
  }
  
  function getContacts() {
    // Perform an address book search. Obtain the 'name' and 'emails' properties 
    // and initially filter the list to Contact records containing 'Bob':
    navigator.service.contacts.find(['name', 'emails'],
                                    successContactFindCallback, 
                                    generalErrorCB,
                                    {filter: 'Bob'}
                                   );
  }
</script>

This code may render as follows within the user agent:

Contact Search via DOM Events
(View as PNG)

If the user clicks on the rendered button element then the user agent may directly provide a contact picker, as defined in API Invocation via DOM Events, utilizing all of the parameters provided in the find() operation as follows:

Contact Picker
(View as PNG)

In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.

If an additional find() operation is called by the current web application before the user has clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a non-null errorCB parameter.

If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR.

If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with the contact information selected by the user provided as the only parameter.

Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke permissions to web applications at a later date.

C. References

C.1 Normative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[UNICODE]
The Unicode Consortium. The Unicode Standard. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

C.2 Informative references

[CONTACTS-WRITER-API]
R. Tibbett. Contacts Writer API. 3rd August 2010. W3C Latest Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/contacts/Writer.html
[DOM-LEVEL-3-EVENTS]
Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 21 December 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema
[RFC2426]
F. Dawson, T. Howes. vCard MIME Directory Profile. September 1998. URL: http://www.ietf.org/rfc/rfc2426.txt
[WIDGETS]
Marcos Caceres. Widget Packaging and Configuration. 01 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20091201/