- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 24 Jun 2010 09:08:03 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv9542/contacts
Modified Files:
Overview.html
Log Message:
Updated spec in line with editor's note requests in http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0265.html
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -d -r1.59 -r1.60
--- Overview.html 16 Jun 2010 10:56:09 -0000 1.59
+++ Overview.html 24 Jun 2010 09:08:01 -0000 1.60
@@ -198,24 +198,24 @@
to this API to reflect requirements or support for privacy-related functionality.
</p>
<p>
- 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.
+ 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.
</p>
<section>
<h2>
Privacy considerations for implementors of the Contacts API
</h2>
<p>
- A <a>user agent</a> must not create, find, save or delete contact information to Web sites without the express permission
- of the user. A <a>user agent</a> 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 <a>user agent</a> must respect revoked permissions.
+ A <a>user agent</a> must not create, find, save or delete contact information to Web sites without the express permission of the
+ user. A <a>user agent</a> 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 <a>user
+ agent</a> must respect revoked permissions.
</p>
<p>
Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same
@@ -458,7 +458,9 @@
Can we remove this attribute? Does a web application need to know the storage location of a Contact record?<br>
<br>
This directly relates to <a
- href="http://www.w3.org/2009/dap/track/issues/43">ISSUE-43</a>.
+ href="http://www.w3.org/2009/dap/track/issues/43">ISSUE-43</a> and discussion thread <a
+ href=
+ "http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0248.html">http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0248.html</a>.
</p>
<p>
An identifier that MAY be provided that represents the address book owner of the current contact object.
@@ -478,8 +480,9 @@
A conforming implementation MUST define a <dfn>default service identifier</dfn> on which to store <a
href="#contact-interface"><code>Contact</code></a> objects that have not yet been assigned to any storage database. The
<a>default service identifier</a> will then be used in the <a
- href="#widl-Contact-save"><code>Contact.save()</code></a> operation when a serviceId is not recognized or when the serviceId
- attribute is <code>null</code>.
+ href='#contact-interface'><code>Contact</code></a> <a
+ href='#widl-Contact-save'>save()</a> operation when a serviceId is not recognized or when the serviceId attribute is
+ <code>null</code>.
</p>
<p>
For all other Contacts sources, it is recommended that the serviceId attribute is assigned as a URI.
@@ -621,15 +624,24 @@
<h2>
<a>ContactProperties</a> interface
</h2>
+ <p
+ class="note">
+ The use of Portable Contacts schema as the format for contacts is subject to further discussions in the group.
+ </p>
<p>
The <a
href="#contactproperties-interface"><code>ContactProperties</code></a> interface captures the settable properties of a contact.
All properties included in this interface have a corresponding definition in [[!POCO-SCHEMA]].
</p>
<p>
- In addition to the properties defined in this interface, a conforming implementation MUST supported both the Singular and Plural
+ 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]].
</p>
+ <p
+ class="note">
+ The inclusion of OpenSocial fields in the paragraph above needs further explanation, particularly in relation to contact database
+ searching and sorting.
+ </p>
<dl
title='[NoInterfaceObject] interface ContactProperties'
class='idl'>
@@ -1087,7 +1099,11 @@
<p>
The <a
href='#contactfindoptions-interface'><code>ContactFindOptions</code></a> interface describes the options that can be applied to
- contact searching.
+ contact searching. When a <a
+ href='#contactfindoptions-interface'><code>ContactFindOptions</code></a> parameter is provided to the <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation, it should be processed according to the provisions detailed in <a
+ href="#options-processing">Options Processing</a>.
</p>
<dl
title='[NoInterfaceObject] interface ContactFindOptions'
@@ -1096,7 +1112,7 @@
attribute String? filter
</dt>
<dd>
- A DOMString-based value with which to search and intially filter the <a
+ A DOMString-based <a>search filter</a> with which to search and intially filter the <a
href='#contacts-interface'><code>Contacts</code></a> database.
</dd>
<dt>
@@ -1104,7 +1120,8 @@
</dt>
<dd>
A boolean value to indicate whether multiple Contact objects are returnable as part of the associated <a
- href='#widl-Contacts-find'><code>Contacts.find()</code></a> method.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</dd>
<dt>
attribute unsigned short? limit
@@ -1143,7 +1160,10 @@
</dt>
<dd>
The Contact objects resulting from the given <a
- href="#widl-Contacts-find"><code>Contacts.find()</code></a> method.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> method. <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a>
</dd>
</dl>
</dd>
@@ -1169,8 +1189,10 @@
</dt>
<dd>
The Contact object resulting from the given <a
- href="#widl-Contact-save"><code>Contact.save()</code></a> or <a
- href="#widl-Contact-remove"><code>Contact.remove()</code></a> method.
+ href='#contact-interface'><code>Contact</code></a> <a
+ href='#widl-Contact-save'>save()</a> or <a
+ href='#contact-interface'><code>Contact</code></a> <a
+ href='#widl-Contact-remove'>remove()</a> method.
</dd>
</dl>
</dd>
@@ -1278,7 +1300,8 @@
</h2>
<p>
The <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> method provides an operation to search for one of more <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> method provides an operation to search for one of more <a
href="#contact-interface"><code>Contact</code></a> objects within the <a
href="contacts-interface"><code>Contacts</code></a> database.
</p>
@@ -1291,21 +1314,25 @@
href="#contactproperties-interface"><code>ContactProperties</code></a> it wishes to obtain in any resulting successful callback.
The <a>search qualifier</a> 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 <a>search qualifier</a> is included within a <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation as the <code>filter</code> parameter.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation as the <code>filter</code> parameter.
</p>
<p>
A <a>search qualifier</a> MUST be specified from a requesting application as a part of any <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</p>
<p>
If the <a>search qualifier</a> provided is of <em>zero-length</em> then the current <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation MUST NOT return any <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation MUST NOT return any <a
href="#contactproperties-interface"><code>ContactProperties</code></a> within any resulting <a
href="#contact-interface"><code>Contact</code></a> object(s).
</p>
<p>
In the case that the <a>search qualifier</a> provided is of <em>non-zero-length</em> then the current <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation MUST return only the matching <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation MUST return only the matching <a
href="#contactproperties-interface"><code>ContactProperties</code></a> within any resulting <a
href="#contact-interface"><code>Contact</code></a> object(s).
</p>
@@ -1313,7 +1340,8 @@
If a specific <a>search qualifier</a> element provided, or <code>filter[x]</code>, does not match any well-known <a
href="#contactproperties-interface"><code>ContactProperties</code></a> attribute, <code>filter[x]</code> SHOULD be ignored when
executing the current <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</p>
<section>
<h3>
@@ -1330,16 +1358,18 @@
of a complex <a
href="#contactproperties-interface"><code>ContactProperties</code></a> attribute in the <a>search qualifier</a> provided to a
<a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</p>
<p>
For example, the <code>name</code> attribute of <a
href="#contactproperties-interface"><code>ContactProperties</code></a> is defined to be of complex type <a
href="#contactname-interface"><code>ContactName</code></a>. Therefore, a requesting application may request either the full
complex attribute (i.e. <code>name</code>) or specific individual attributes of this complex attribute (i.e.
- <code>name.formatted</code>, <code>name.familyName</code>, <code>name.givenName</code>, <code>name.middleName</code>, <code>name.honorificPrefix</code>,
- <code>name.honorificSuffix</code>) as part of a <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation's <a>search qualifier</a>.
+ <code>name.formatted</code>, <code>name.familyName</code>, <code>name.givenName</code>, <code>name.middleName</code>,
+ <code>name.honorificPrefix</code>, <code>name.honorificSuffix</code>) as part of a <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation's <a>search qualifier</a>.
</p>
<p>
In the case that a complex <a
@@ -1395,16 +1425,18 @@
</h3>
<p>
By default, the <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation MUST return either an empty sequence or a single <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation MUST return either an empty sequence or a single <a
href="#contact-interface"><code>Contact</code></a> object, accessible as part of the sequence returned in the <a
href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</code></a> callback function.
</p>
<p>
If a <a
href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object is provided to the <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation and its <code>multiple</code> attribute is set to
- <code>true</code>, the <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation MUST return either an empty sequence, a single <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation and its <code>multiple</code> attribute is set to <code>true</code>, the <a
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation MUST return either an empty sequence, a single <a
href="#contact-interface"><code>Contact</code></a> object or <var>[X]</var> number of <a
href="#contact-interface"><code>Contact</code></a> objects, accessible as part of the sequence returned in the <a
href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</code></a> callback function.
@@ -1417,16 +1449,18 @@
<p>
If a <a
href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object is provided to the <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation and its <code>limit</code> attribute is greater than
- zero and less than or equal to the implementation's <a>upper cardinality limit</a>, then <var>[X]</var> MUST be set to the
- provided <code>limit</code> value.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation and its <code>limit</code> attribute is greater than zero and less than or
+ equal to the implementation's <a>upper cardinality limit</a>, then <var>[X]</var> MUST be set to the provided
+ <code>limit</code> value.
</p>
<p>
The <code>limit</code> attribute is <dfn>out of bounds</dfn> if a <a
href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object is provided to the <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation and its <code>limit</code> attribute is less than or
- equal to zero or greater than the implementation's <a>upper cardinality limit</a>. In this case <var>[X]</var> MUST be set
- to the implementation's <a>upper cardinality limit</a>.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation and its <code>limit</code> attribute is less than or equal to zero or greater
+ than the implementation's <a>upper cardinality limit</a>. In this case <var>[X]</var> MUST be set to the
+ implementation's <a>upper cardinality limit</a>.
</p>
</section>
<section>
@@ -1435,19 +1469,22 @@
</h4>
<p>
The <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation must return successful callback results according to the
- sorting guidelines defined in this section.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation must return successful callback results according to the sorting guidelines
+ defined in this section.
</p>
<p>
A <dfn>search weight</dfn> is a numeric value defined for each attribute in a <a
href="#contact-interface"><code>Contact</code></a> object. A lower value denotes a higher placing in the ultimate sorting of
<a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> results.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> results.
</p>
<p>
For example, if a <a>search filter</a> of 'Bob' matches to <code>name.givenName</code> in Object A and to
<code>displayName</code> in Object B, Object B will be the first result object returned from the successCB of the given <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation, followed by Object A.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation, followed by Object A.
</p>
<p
class="note">
@@ -1465,7 +1502,8 @@
href="#contact-interface"><code>Contact</code></a> objects in which it is interested. The <a>search filter</a> is included as
the <code>filter</code> attribute of the <a
href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object provided to a <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</p>
<p>
A <a>search filter</a> is used to search all the fields of a <a
@@ -1502,7 +1540,8 @@
The <dfn>rules for processing search filters</dfn> is defined below and is always provided with a <var
title="filter">filter</var> parameter, representing the <code>filter</code> attribute of the <a
href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> parameter provided within the current <a
- href="#widl-contacts-find"><code>Contacts.find()</code></a> operation.
+ href="#contacts-interface"><code>Contacts</code></a> <a
+ href="#widl-Contacts-find">find()</a> operation.
</p>
<dl
class='switch'>
Received on Thursday, 24 June 2010 09:08:05 UTC