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:
window.navigator.people.find( filter, fields, successCallback, failureCallback)
The arguments are interpreted as follows:
- filter is an object that expresses a set of substring matches that must be met by contacts to be included in the result set. The attributes of the object are the fields that will be searched, and the values are the substrings that must be found.
For example, a filter of { emails: "@mozilla.com" } will include only contacts whose emails list contains at least one object that contains the substring "@mozilla.com".
- fields 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.
For example, a fields argument could be ["displayName", "emails", "phoneNumbers"].
Also note the special field argument "idHash", which returns to MD5 hash of all the email addresses of the contact. (TODO: automatically salt the hash with the hostname?)
- successCallback 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]);
}
}
- failureCallback 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;
}