Labs/Contacts/ContentAPI: Difference between revisions

← Older edit

Labs/Contacts/ContentAPI (view source)

Revision as of 20:35, 24 January 2012

1,304 bytes added , 24 January 2012

update warnings to indicate different scopes of efforts / related work

Tantek

canmove, Confirmed users

2,848

edits

@@ Line 1: / Line 1: @@
+== WARNING ==
+'''WARNING: the content of this page is over a year old and may be out-of-date / inaccurate with respect to current Contacts / ContentAPI thinking.'''
+Please see:
+* The [[WebAPI/ContactsAPI|ContactsAPI]] for current device-centric WebAPI for accessing device contacts.
+There are still use-cases for a higher-level more "appy" Contacts API that allows web apps to both access contacts and be a provider for contacts, for that see work on:
+* [[WebActions]]
+* [[WebActvities]]
+- [[User:Tantek|Tantek]]
+== Summary ==
 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.
@@ Line 9: / Line 22: @@
 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.
+* <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>.
-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?)
 * <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.
@@ Line 31: / Line 43: @@
   }
-* <tt>options</tt> 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.
+* <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 filter of <tt>{ emails: "@mozilla.com" }</tt> will include only contacts whose <tt>emails</tt> list contains at least one object that contains the substring "@mozilla.com".
+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 ==
+'''WARNING: this section as well as Portable Contacts are out-of-date as of 2012 with the latest converged web contacts schemas.'''
+See [[vCard4]] and [[WebAPI/ContactsAPI]]. - [[User:Tantek|Tantek]] 17:37, 10 January 2012 (PST)
+----
 The schema for Contacts is [http://portablecontacts.net/draft-spec.html| Portable Contacts version 1.0].
@@ Line 66: / Line 83: @@
 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:
@@ Line 83: / Line 102: @@
 ** <tt>getPhotos(callback)</tt>: a function that, when invoked, returns an array of photo objects through the callback (see below)
-* <tt>picturesOf(callback)</tt> invokes the callback, passing an array of objects representing photos of the contact.  The objects are photos, 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:
-* The getPhotos (of a collection) and picturesOf methods produce a list of pictures  The fields of each picture 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
@@ Line 92: / Line 109: @@
 * <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.)