Contacts API

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.

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 3rd parties users are, more often than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd 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 3rd 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 centre 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.

The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement all fields defined in this specification.

2.1 Usage Examples

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'}
                               );

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 create, find, save and remove contact information from a user's address book(s). All API methods disclose 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. 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 creatable, retrivable, updateable or removable without the user's express permission.

3.1 Privacy considerations for implementors of the Contacts API

A user agent must not create, find, save or delete 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 URI of the document origin, as defined in [HTML5]. 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, as defined in [HTML5], 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 create, find, save or remove 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 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 creation, retrieval, update and/or removal of contact information.

3.2 Privacy considerations for recipients of contact information

Recipients must only request contact information when necessary. Recipients must only use the contact information for the task for which it was provided to them. Recipients must dispose of contact information once that task is completed, unless expressly permitted to retain it by the user. Recipients must 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 must not retransmit the contact information without the user's express permission. Care should be taken when retransmitting and use of encryption is encouraged.

Recipients must 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 must 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, such that they may be created, found, read, updated, and deleted.

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

[NoInterfaceObject]
interface Contacts {
    PendingOp find (in DOMString[] fields, in ContactFindSuccessCB 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:

If a current find(), save() or remove() operation is pending a response, and the method was invoked with a non-null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code.
Search for contacts in the address book according to the rules defined in Contact Search Processing.
If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.

Parameter	Type	Nullable	Optional	Description
fields	`DOMString[]`	✘	✘	The search qualifier.
successCB	`ContactFindSuccessCB`	✘	✘	Function to call when the asynchronous operation completes
errorCB	`ContactErrorCB`	✔	✔	Function to call when the asynchronous operation fails.
options	`ContactFindOptions`	✔	✔	The options to apply to the output of this method.

No exceptions.

Return type: PendingOp

4.3 `Contact` interface

The use of Portable Contacts schema as the format for contacts is subject to further discussions in the group.

The Contact interface captures the properties of a contact object. All properties included in this interface have a corresponding definition in [POCO-SCHEMA].

In addition to the properties defined in this interface, a conforming implementation must support both the Singular and Plural OpenSocial fields defined in [POCO-SCHEMA].

The inclusion of OpenSocial fields in the paragraph above needs further explanation, particularly in relation to contact database searching and sorting.

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.

[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 DOMString             published;
             attribute DOMString             updated;
             attribute DOMString             birthday;
             attribute DOMString             anniversary;
             attribute DOMString             gender;
             attribute DOMString             note;
             attribute DOMString             preferredUsername;
             attribute ContactField[]        photos;
             attribute ContactField[]        tags;
             attribute ContactField[]        relationships;
             attribute ContactField[]        urls;
             attribute ContactAccount[]      accounts;
             attribute DOMString             utcOffset;
             attribute DOMString             connected;
};

4.3.1 Attributes

accounts of type array of ContactAccount

See [[POCO-SCHEMA] Section 7.2.2. accounts].

No exceptions.

addresses of type array of ContactAddress

See [[POCO-SCHEMA] Section 7.2.2. addresses].

No exceptions.

anniversary of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. anniversary].

No exceptions.

birthday of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. birthday].

No exceptions.

connected of type DOMString

Ignore this [POCO-SCHEMA] attribute?

See [[POCO-SCHEMA] Section 7.2.1. connected].

No exceptions.

displayName of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. displayName].

No exceptions.

emails of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. emails].

No exceptions.

gender of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. gender].

No exceptions.

id of type DOMString, readonly

A globally unique identifier for the given Contact object. Each Contact referenced from Contacts 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.

See [[POCO-SCHEMA] Section 7.2.1. id] for additional definition of this attribute.

No exceptions.

ims of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. ims].

No exceptions.

name of type ContactName

See [[POCO-SCHEMA] Section 7.2.1. name].

No exceptions.

nickname of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. nickname].

No exceptions.

note of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. note].

No exceptions.

organizations of type array of ContactOrganization

See [[POCO-SCHEMA] Section 7.2.2. organizations].

No exceptions.

phoneNumbers of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. phoneNumbers].

No exceptions.

photos of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. photos].

No exceptions.

preferredUsername of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. preferredUsername].

No exceptions.

published of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. published].

No exceptions.

relationships of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. relationships].

No exceptions.

tags of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. tags].

No exceptions.

updated of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. updated].

No exceptions.

urls of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. urls].

No exceptions.

utcOffset of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. utcOffset].

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: See [[POCO-SCHEMA]] Section 7.3. familyName].

No exceptions.
formatted of type DOMString: See [[POCO-SCHEMA]] Section 7.3. formatted].

No exceptions.
givenName of type DOMString: See [[POCO-SCHEMA]] Section 7.3. givenName].

No exceptions.
honorificPrefix of type DOMString: See [[POCO-SCHEMA]] Section 7.3. honorificPrefix].

No exceptions.
honorificSuffix of type DOMString: See [[POCO-SCHEMA]] Section 7.3. honorificSuffix].

No exceptions.
middleName of type DOMString: See [[POCO-SCHEMA]] Section 7.3. middleName].

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   primary;
};

4.5.1 Attributes

primary of type boolean: See [[POCO-SCHEMA]] Section 7.2.2. primary].

No exceptions.
type of type DOMString: See [[POCO-SCHEMA]] Section 7.2.2. type].

No exceptions.
value of type DOMString: See [[POCO-SCHEMA]] Section 7.2.2. value].

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: See [[POCO-SCHEMA]] Section 7.4. country].

No exceptions.
formatted of type DOMString: See [[POCO-SCHEMA]] Section 7.4. formatted].

No exceptions.
locality of type DOMString: See [[POCO-SCHEMA]] Section 7.4. locality].

No exceptions.
postalCode of type DOMString: See [[POCO-SCHEMA]] Section 7.4. postalCode].

No exceptions.
region of type DOMString: See [[POCO-SCHEMA]] Section 7.4. region].

No exceptions.
streetAddress of type DOMString: See [[POCO-SCHEMA]] Section 7.4. streetAddress].

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;
    attribute DOMString startDate;
    attribute DOMString endDate;
    attribute DOMString location;
    attribute DOMString description;
};

4.7.1 Attributes

department of type DOMString: See [[POCO-SCHEMA]] Section 7.5. department].

No exceptions.
description of type DOMString: See [[POCO-SCHEMA]] Section 7.5. description].

No exceptions.
endDate of type DOMString: See [[POCO-SCHEMA]] Section 7.5. endDate].

No exceptions.
location of type DOMString: See [[POCO-SCHEMA]] Section 7.5. location].

No exceptions.
name of type DOMString: See [[POCO-SCHEMA]] Section 7.5. name].

No exceptions.
startDate of type DOMString: See [[POCO-SCHEMA]] Section 7.5. startDate].

No exceptions.
title of type DOMString: See [[POCO-SCHEMA]] Section 7.5. title].

No exceptions.

4.8 `ContactAccount` interface

The ContactAccount interface is a reusable component that is used to support contact accounts within the Contact interface.

[NoInterfaceObject]
interface ContactAccount {
    attribute DOMString domain;
    attribute DOMString username;
    attribute DOMString userid;
};

4.8.1 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.

4.9 `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 String?         filter;
    attribute boolean?        multiple;
    attribute unsigned short? limit;
    attribute DOMString       updatedSince;
};

4.9.1 Attributes

filter of type String, nullable

A DOMString-based search filter with which to search and intially filter the Contacts database.

No exceptions.

limit of type unsigned short, nullable

The maximum number of results to return from the contacts search.

This parameter only applies in the case that the associated multiple attribute is equal to true.

If no value is provided, the search will return all Contact object results.

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.

No exceptions.

updatedSince of type DOMString

Return only contact records that have been updated on or after the given time, specified as an xs:dateTime.

This filter is based on the updated field as defined in Contact.

No exceptions.

4.10 `ContactFindSuccessCB` interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindSuccessCB {
    void onSuccess (in Contact[] contactObjs);
};

4.10.1 Methods

onSuccess

Parameter	Type	Nullable	Optional	Description
contactObjs	`Contact[]`	✘	✘	The Contact objects resulting from the given `Contacts` find() method. `Contacts` find()

No exceptions.

Return type: void

4.11 `ContactErrorCB` interface

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

4.11.1 Methods

onError

Parameter	Type	Nullable	Optional	Description
error	`ContactError`	✘	✘	The Contact API related error object.

No exceptions.

Return type: void

4.12 `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 NOT_FOUND_ERROR = 2;
    const unsigned short TIMEOUT_ERROR = 3;
    const unsigned short PENDING_OPERATION_ERROR = 4;
    const unsigned short IO_ERROR = 5;
    const unsigned short NOT_SUPPORTED_ERROR = 6;
    const unsigned short PERMISSION_DENIED_ERROR = 20;
    readonly attribute unsigned short code;
};

4.12.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.12.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_FOUND_ERROR of type unsigned short: If no response information can be provided from the requested method.
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(), save() or remove() 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 Complex Search Qualifiers

Certain Contact attributes can be considered complex by the fact that the information they contain is available only through child DOMString-based attributes of a complex Object object.

In such cases, a requesting application must be able to request both the full complex Contact attribute and also be able to request individual parts of a complex 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 complex type ContactName. Therefore, a requesting application may request either the full complex attribute (i.e. name) or specific individual attributes of this complex 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 complex Contact attribute is defined as a sequence or array of complex objects, specific individual attributes can be referenced by using the complex 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 complex attribute an application would request e.g. addresses.locality, addresses.region, etc.

5.1.2 Search Qualifier Example

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:

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 ContactFindSuccessCB 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 ContactFindSuccessCB callback function.

An implementation must specify a suitable integer-based upper cardinality limit to limit the maximum number of Contact objects that may be returned in the case that the multiple flag is true and the limit flag is out of bounds.

If a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is greater than zero and less than or equal to the implementation's upper cardinality limit, then [X] must be set to the provided limit value.

The limit attribute is out of bounds if a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is less than or equal to zero or greater than the implementation's upper cardinality limit. In this case [X] must be set to the implementation's upper cardinality limit.

5.2.2 Search Sorting

The Contacts find() operation must return successful callback results according to the sorting guidelines defined in this section.

A search weight is a numeric value defined for each attribute in a Contact object. A lower value denotes a higher placing in the ultimate sorting of Contacts find() results. The search weights for each Contact attribute are defined in Appendix B.

For example, if a search filter of 'Bob' matches to name.givenName in Object A and to displayName in Object B, Object B will be the first result object returned from the successCB of the given Contacts find() operation, followed by Object A.

Include UNICODE guidelines for intra-attribute sorting of results (where multiple Contact objects match on the same attribute)... [UNICODE] DUCET

5.2.3 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 ContactFindSuccessCB.

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) and the displayName 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 Object object.

If filter is a DOMString object

Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5.
Let partialMatchFound be the result of applying the partial matching algorithm, providing filter and contactset as inputs.
If partialMatchFound is true, add contactset to contactsresult.
Go to step 1.
Sort contactsresult according to the guidelines in Search Sorting.
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

Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5.
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.
If hasPartialMatch is true, go to step 5.
Go to step 1.
Return hasPartialMatch.

If contactset is another native object type

Return false.

5.2.3.1 Search Filter Example

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:

Using ECMA-262 3rd Edition regular expression syntax and psuedo-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. Search ordering is sorted according to search weights defined in Search Filters and described in Appendix B.

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, as defined in Search Filters.
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.

A. 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, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that this specification enables.

A.1 Sharing Contact Information

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

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'}
                               );

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(), save() or remove() 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, utilising 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 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 ContactFindSuccessCB 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. Search Weights

The following table defines the search weight values for each search qualifier provided in this specification.

Search Qualifier	Search Weight
`displayName`	1
`name.formatted`	2
`nickname`	3
`tags.value`	4
`phoneNumbers.value`	5
`addresses.formatted`	6
`organizations.name`	7
`emails.value`	8
`ims.value`	9
`preferredUsername`	10
`name.familyName`	11
`name.givenName`	12
`name.middleName`	13
`addresses.country`	14
`addresses.region`	15
`addresses.streetAddress`	16
`addresses.locality`	17
`addresses.postalCode`	18
`organizations.department`	19
`organizations.title`	20
`organizations.startDate`	21
`organizations.endDate`	22
`organizations.location`	23
`organizations.description`	24
`accounts.domain`	25
`accounts.userid`	26
`accounts.username`	27
`photos.value`	28
`relationships.value`	29
`urls.value`	30
`gender`	31
`birthday`	32
`anniversary`	33
`published`	34
`updated`	35
`utcOffset`	36
`notes`	37
`name.honorificPrefix`	38
`name.honorificSuffix`	39
`phoneNumbers.type`	40
`addresses.type`	41
`emails.type`	42
`ims.type`	43
`tags.type`	44
`photos.type`	45
`relationships.type`	46
`urls.type`	47
`connected`	48
`id`	49
`phoneNumbers.primary`	n/a (boolean attribute)
`addresses.primary`	n/a (boolean attribute)
`emails.primary`	n/a (boolean attribute)
`ims.primary`	n/a (boolean attribute)
`tags.primary`	n/a (boolean attribute)
`photos.primary`	n/a (boolean attribute)
`relationships.primary`	n/a (boolean attribute)
`urls.primary`	n/a (boolean attribute)
`phoneNumbers`	n/a (complex attribute)
`addresses`	n/a (complex attribute)
`emails`	n/a (complex attribute)
`ims`	n/a (complex attribute)
`photos`	n/a (complex attribute)
`tags`	n/a (complex attribute)
`relationships`	n/a (complex attribute)
`urls`	n/a (complex attribute)

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/
[POCO-SCHEMA]: Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema
[RFC2119]: S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. 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
[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/

Contacts API

W3C Working Draft 17 August 2010

Abstract

Status of This Document

Table of Contents

1. Conformance

2. Introduction

2.1 Usage Examples

3. Security and Privacy Considerations

3.1 Privacy considerations for implementors of the Contacts API

3.2 Privacy considerations for recipients of contact information

3.3 Additional implementation considerations

4. API Description

4.1 ServiceContacts interface

4.1.1 Attributes

4.2 Contacts interface

4.2.1 Methods

4.3 Contact interface

4.3.1 Attributes

4.4 ContactName interface

4.4.1 Attributes

4.5 ContactField interface

4.5.1 Attributes

4.6 ContactAddress interface

4.6.1 Attributes

4.7 ContactOrganization interface

4.7.1 Attributes

4.8 ContactAccount interface

4.8.1 Attributes

4.9 ContactFindOptions interface

4.9.1 Attributes

4.10 ContactFindSuccessCB interface

4.10.1 Methods

4.11 ContactErrorCB interface

4.11.1 Methods

4.12 ContactError interface

4.12.1 Attributes

4.12.2 Constants

5. Contact Search Processing

5.1 Search Qualifiers

5.1.1 Complex Search Qualifiers

5.1.2 Search Qualifier Example

5.2 Options Processing

5.2.1 Search Cardinality

5.2.2 Search Sorting

5.2.3 Search Filters

5.2.3.1 Search Filter Example

A. User Interaction Guidelines

A.1 Sharing Contact Information

B. Search Weights

C. References

C.1 Normative references

C.2 Informative references

4.1 `ServiceContacts` interface

4.2 `Contacts` interface

4.3 `Contact` interface

4.4 `ContactName` interface

4.5 `ContactField` interface

4.6 `ContactAddress` interface

4.7 `ContactOrganization` interface

4.8 `ContactAccount` interface

4.9 `ContactFindOptions` interface

4.10 `ContactFindSuccessCB` interface

4.11 `ContactErrorCB` interface

4.12 `ContactError` interface