Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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].
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.
ServiceContacts
interface
Contacts
interface
Contact
interface
ContactName
interface
ContactField
interface
ContactAddress
interface
ContactOrganization
interface
ContactFindOptions
interface
ContactFindCB
interface
ContactErrorCB
interface
ContactError
interface
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.
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 */)
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.
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.
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.
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.
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.
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;
};
contacts
of type Contacts
, readonlyContacts
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);
};
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:
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.
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
fields | DOMString[] | ✘ | ✘ | The search qualifier. |
successCB |
| ✘ | ✘ | Function to call when the asynchronous operation completes |
errorCB |
| ✔ | ✔ | Function to call when the asynchronous operation fails. |
options |
| ✔ | ✔ | The options to apply to the output of this method. |
caller PendingOp
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;
};
addresses
of type array of ContactAddress
This attribute represents one or more physical addresses associated with this Contact.
birthday
of type DateThis 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.
categories
of type array of DOMStringThis attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favorite".
displayName
of type DOMStringThis 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.
emails
of type array of ContactField
This attribute represents one or more email addresses associated with this Contact.
gender
of type DOMStringThis 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.
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.
ims
of type array of ContactField
This attribute represents one or more instant messaging identifiers associated with this Contact.
name
of type ContactName
This attribute represents the full name of this Contact
indicated by the name
components associated with the ContactName
object.
nickname
of type DOMStringThis attribute contains the nickname (or a casual name) for this Contact.
note
of type DOMStringThis 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
).
organizations
of type array of ContactOrganization
This attribute represents one or more organizations associated with this Contact.
phoneNumbers
of type array of ContactField
This attribute represents one or more phone numbers associated with this Contact.
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.
revision
of type DateThis 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.
timezone
of type DOMStringThe 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.
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
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;
};
familyName
of type DOMStringThis attribute contains the family name (also referred to as the last name) of this Contact.
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
).
givenName
of type DOMStringThis attribute contains the given name (also referred to as the first name) of this Contact.
honorificPrefix
of type DOMStringThis attribute contains the honorific prefix (or title) of this Contact. E.g. Mr. Dr. Ms. Mrs.,
honorificSuffix
of type DOMStringThis attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr.
middleName
of type DOMStringThis attribute contains the middle name of this Contact.
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;
};
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.
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.
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.
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;
};
country
of type DOMString
This attribute contains the country name corresponding to this ContactAddress
.
formatted
of type DOMStringThis attribute contains the full physical address including street, locality, region, postalCode, and country as appropriate, and formatted for display.
locality
of type DOMString
This attribute contains the locality (or city) name corresponding to this ContactAddress
.
postalCode
of type DOMString
This attribute contains the postal code (or zip) corresponding to this ContactAddress
.
region
of type DOMString
This attribute contains the region (or state/province) name corresponding to this ContactAddress
.
streetAddress
of type DOMString
This attribute contains the street address corresponding to this ContactAddress
.
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;
};
department
of type DOMStringThis attribute contains the Job Title information of the Contact associated with this Organization.
name
of type DOMStringThis attribute contains the name of the Organization and must be assigned a non-null value.
title
of type DOMStringThis attribute contains the department information of the Organization associated with this Contact.
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;
};
filter
of type DOMString, nullableContacts
database.
multiple
of type boolean, nullableContacts
find() operation.
By default this option is set to true
.
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
.
ContactFindCB
interface
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindCB : PendingOp {
void onsuccess (in Contact
[] contactObjs);
};
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
|
ContactErrorCB
interface
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactErrorCB : PendingOp {
void onerror (in ContactError
error);
};
onerror
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
error |
| ✘ | ✘ | The Contact API related error object. |
void
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
|
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;
};
code
of type unsigned short, readonlyINVALID_ARGUMENT_ERROR
of type unsigned shortIO_ERROR
of type unsigned shortNOT_SUPPORTED_ERROR
of type unsigned shortPENDING_OPERATION_ERROR
of type unsigned shortPERMISSION_DENIED_ERROR
of type unsigned shortTIMEOUT_ERROR
of type unsigned shortUNKNOWN_ERROR
of type unsigned short
The Contacts
find() method provides an operation to search for one of more Contact
objects within the Contacts
database.
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.
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:
Contact
attributes requested in the provided search qualifier
(name
, emails.value
- friends
is not a valid Contact
attribute so ignore this element).
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.
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.
Contacts
database.
Let contactsresult be initially an empty Array object.
true
, add contactset to contactsresult.
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:
false
.
true
, go to step 5.
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:
( 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 )
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.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.
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;
};
Xaccounts
of type array of ContactAccount
accounts
].
[NoInterfaceObject]
interface ContactAccount {
attribute DOMString domain;
attribute DOMString username;
attribute DOMString userid;
};
domain
of type DOMString
See [[POCO-SCHEMA] Section 7.6. domain
].
userid
of type DOMString
See [[POCO-SCHEMA] Section 7.6. userid
].
username
of type DOMString
See [[POCO-SCHEMA] Section 7.6. username
].
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
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]:
click
dblclick
mouseup
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.
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.
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:
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:
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.
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:
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:
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.