View source for Labs/Contacts/ContentAPI

The Contacts add-on adds a database of contact data to the browser, and allows web pages to request data from this database to use in web content.

== Exposed Functions ==

In a Firefox web browser which has installed the Contacts addon, the following new method becomes available to web content:

<tt>window.navigator.service.contacts(fields, successCallback, failureCallback, options) </tt>

The arguments are interpreted as follows:

* <tt>fields</tt> is an array of strings that express which fields of the contact will be made available to the web page.  The strings should be drawn from the set of known properties described in "Contact Schema", below.  The user will be asked to confirm each of the fields, and may choose to deny access to some fields, in which case the web page will receive a subset of what was requested. To get a more specific property, use the "." operator as specified in the W3C contacts API.

For example, a fields argument could be <tt>["displayName", "emails", "phoneNumbers", "name.givenName"]</tt>.


* <tt>successCallback</tt> is a function that will be called when the contact result set is found.  It takes a single argument, which is an array of objects.

For example, the success callback could be 
 function(people) { 
  for (var i=0;i<people.length;i++) {
   processPerson(people[i]);
  }
 }

* <tt>failureCallback</tt> is a function that will be called if the lookup fails.  It takes a single argument, which is an explanatory string.

For example, the failure callback could be
 function(error) {
  $("errorMsg").innerHTML = "Unable to load contacts: " + error;
 }

* <tt>options</tt> is an object that expresses the various options allowed in the W3C contacts API.  The options allowed are "filter", "multiple", "limit", and "updatedSince".  "filter" allows for filtering of contacts based on pattern matching.  "multiple" allows for multiple contacts to be returned. "limit" specifies a limit of contacts to be returned. Finally, "updatedSince" specifies only contacts that have been updated after a certain time. More in-depth explanations of the options are detailed in the W3C contacts spec.

For example, a options of <tt>{ filter:"paul", multiple:true, limit:5, updatedSince:"2009-10-10T12:00:00-05:00" }</tt> will include only five contacts where one of the fields requested contains the substring "paul" (case insensitive) and the contact has been updated after October 10, 2009.

== Contact Schema ==

The schema for Contacts is [http://portablecontacts.net/draft-spec.html| Portable Contacts version 1.0].

Importers will coerce data into this format when necessary.  The most relevant fields for web pages that are consuming this data are:

* displayName
* name (with subproperties givenName and familyName)
* emails (list; objects have type and value)
* phoneNumbers (list; objects have type and value)
* addresses (list; objects have streetAddress, locality, city, country, postalCode)
* accounts (list; objects have domain, userid, username)
* photos (list; objects have type and value; "thumbnail" and "profile" are canonical types)

== Deltas from W3C Contacts API ==

The W3C Device APIs and Policy Working Group is working to standardize a Contacts API for web-enabled devices; you can [http://www.w3.org/TR/contacts-api/ | read the latest draft here].

The Firefox implementation is lagging behind that API a bit; notable differences include:

* W3C API does not define default value for the "multiple" option should it be omitted. The Firefox implementation has it to be true.
* W3C API includes "save", "remove", and "clone" operations.
* W3C API includes error codes rather than strings for error callbacks

== Experimental "Services" API ==

In version 0.4 and later of the Contacts add-on, experimental service support is included.

The services API adds a "services" property to the Contact object, which has one or more functions attached to it that allow interaction with a contact's social web services.

The implementation of these services is variable, depending on the web service involved, but the names and APIs of the service methods are designed to allow for a degree of interoperability and automatic discovery of a person's "social API".

To enable this API, set "extensions.mozillalabs.contacts.allowServices" to true in about:config.

At present, the services API includes the following methods:

* <tt>updates(callback)</tt> invokes the callback repeatedly, passing an array of objects representing recent updates.  The properties of the update object are:
** <tt>text</tt>: always present; a short text message
** <tt>source</tt>: always present; the name of the service that provided the update
** <tt>sourceLink</tt>: always present; a link to the page of the service that provided the update
** <tt>link</tt>: optional; a link to more detail for the update

* <tt>pictureCollectionsBy(callback)</tt> invokes the callback repeatedly, passing an array of objects representing photo collections managed by the user.  The properties of each photoCollection are:
** <tt>name</tt>: always present; a name for the collection
** <tt>created_time</tt>: optional; the time the collection was created, in a form that <tt>new Date()</tt> can parse.
** <tt>location</tt>: optional; a location for the collection
** <tt>primaryPhotoThumbnailURL</tt>: optional; a URL to an image that is a thumbnail for the collection
** <tt>primaryPhotoURL</tt>: optional; a URL for more detail about the primaryPhoto
** <tt>getPhotos(callback)</tt>: a function that, when invoked, returns an array of photo objects through the callback (see below)

* <tt>picturesOf(callback)</tt> produces a list of pictures by invoking a callback repeatedly with an array of pictures.  The fields of each photo object are:
** <tt>name</tt>: optional; a filename or label for the picture
** <tt>homeURL</tt>: the URL of a page containing more detail about a picture
** <tt>location</tt>: optional; the location of the picture
** <tt>photoThumbnailURL</tt>: a URL to an image that is a thumbnail of this image

* <tt>sendPrivateMessageTo(message, callback)</tt> submits the given message to a service of the contact that will deliver the message privately.  (Note that the message may be subject to significant restrictions; we need to provide a better API to understand character limits, two-way permissions, etc.)

* <tt>sendPublicMessageTo(message, callback)</tt> submits the given message to a service of the contact that will deliver the message publicly.  (Note that the message may be subject to significant restrictions; we need to provide a better API to understand character limits, two-way permissions, etc.)