- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 05 Jul 2010 15:37:00 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv15660/contacts
Modified Files:
Overview.html
Log Message:
- Changed back to Editor's Draft (was: marked as Working Draft)
- Removal of serviceId (see: http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0321.html)
- Updates from feedback (see: http://lists.w3.org/Archives/Public/public-device-apis/2010Jul/0008.html)
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.66
retrieving revision 1.67
diff -u -d -r1.66 -r1.67
--- Overview.html 30 Jun 2010 14:56:40 -0000 1.66
+++ Overview.html 5 Jul 2010 15:36:58 -0000 1.67
@@ -1,7 +1,9 @@
<!DOCTYPE html>
<html>
<head>
- <title>Contacts API</title>
+ <title>
+ Contacts API
+ </title>
<meta
http-equiv='Content-Type'
content='text/html;charset=utf-8'>
@@ -19,12 +21,11 @@
type="text/javascript"
class='remove'>
var respecConfig = {
- specStatus: "WD",
+ specStatus: "ED",
shortName: "contacts-api",
- editors: [{name: "Richard Tibbett", company: "Invited Expert"}],
- publishDate: "2010-07-01",
- previousPublishDate: "2010-01-21",
- previousMaturity: "FPWD",
+ editors: [{name: "Richard Tibbett", company: "Invited Expert"}],
+ //publishDate: "2010-07-01",
+ // previousPublishDate: "2010-01-21",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/",
// lcEnd: "2009-08-05",
};
@@ -309,15 +310,7 @@
updated, and deleted.
</p>
<p>
- Multiple address books, taken from different sources, can be represented within this unified address book interface. Contacts
- from different sources can be distinguished using the <a
- href='#widl-Contact-serviceId'><code>serviceId</code></a> field.. In addition, multiple address books can be displayed
- by filtering on the required <a
- href='#widl-Contact-serviceId'><code>serviceId</code></a> value via the <code>Contacts</code> <a
- href='#widl-Contacts-find'>find()</a> function.
- </p>
- <p>
- Equally, multiple contact groups can be represented within this unified address book by specifying consistent <a
+ Multiple contact groups can be represented within this unified address book by specifying consistent <a
href='#widl-ContactProperties-tags'><code>tags</code></a> value(s) as part of individual <a
href="#contact-interface"><code>Contact</code></a> objects. Multiple contact groups can be displayed by filtering on the
required <a
@@ -367,7 +360,8 @@
</p>
<ol>
<li>
- If a current find(), save() or remove() operation is pending a response, invoke the <code>errorCB</code> with a <a
+ If a current find(), save() or remove() operation is pending a response, and the method was invoked with a
+ non-<code>null</code> <code>errorCB</code> argument, invoke the <code>errorCB</code> with a <a
href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> code.
</li>
<li>
@@ -449,45 +443,6 @@
</p>
</dd>
<dt>
- attribute DOMString? serviceId
- </dt>
- <dd>
- <p
- class="note">
- 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> 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.
- </p>
- <p>
- This attribute enables multiple address book sources to be tagged and filtered on Contact objects.
- </p>
- <p>
- The following constants are defined for use in the <code>serviceId</code> attribute for addressing non-networked storage
- databases:
- </p>
-<pre>
-
-'uicc', 'device'.
-</pre>
- <p>
- 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='#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.
- </p>
- </dd>
- <dt>
Contact clone ()
</dt>
<dd>
@@ -510,23 +465,17 @@
href="#contacts-interface"><code>Contacts</code></a>.
</p>
<p>
- This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object , as defined in
+ This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
[[!CORE-DEVICE]], and then asynchronously starts a <dfn>save contact process</dfn> defined as follows:
</p>
<ol>
<li>
- If a current find(), save() or remove() operation is pending a response, invoke the <code>errorCB</code> with a <a
+ If a current find(), save() or remove() operation is pending a response, and the method was invoked with a
+ non-<code>null</code> <code>errorCB</code> argument, invoke the <code>errorCB</code> with a <a
href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> code.
</li>
<li>
If the current <a
- href='#widl-Contact-serviceId'><code>Contact.serviceId</code></a> value is not recognized in <a
- href='#contacts-interface'><code>Contacts</code></a> or a <a
- href='#widl-Contact-serviceId'><code>Contact.serviceId</code></a> value has not been set, create and set a new <a
- href='#widl-Contact-serviceId'><code>Contact.serviceId</code></a> value to the <a>default service identifier</a>.
- </li>
- <li>
- If the current <a
href='#widl-Contact-id'><code>Contact.id</code></a> value is not recognized in <a
href='#contacts-interface'><code>Contacts</code></a> or a <a
href='#widl-Contact-id'><code>Contact.id</code></a> value has not been set, create and set a new <a
@@ -582,7 +531,8 @@
</p>
<ol>
<li>
- If a current find(), save() or remove() operation is pending a response, invoke the <code>errorCB</code> with a <a
+ If a current find(), save() or remove() operation is pending a response, and the method was invoked with a
+ non-<code>null</code> <code>errorCB</code> argument, invoke the <code>errorCB</code> with a <a
href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> code.
</li>
<li>
@@ -592,8 +542,7 @@
<li>
If the removal of the current object from <a
href='#contacts-interface'><code>Contacts</code></a> was successful, set the current object's <a
- href='#widl-Contact-id'><code>Contact.id</code></a> value to <code>null</code> and the current object's <a
- href='#widl-Contact-serviceId'><code>Contact.serviceId</code></a> value to <code>null</code>.
+ href='#widl-Contact-id'><code>Contact.id</code></a> value to <code>null</code>.
</li>
<li>
If successful, invoke the associated <code>successCB</code>. If the attempt fails, and the method was invoked with a
@@ -1349,7 +1298,7 @@
href="#contact-interface"><code>Contact</code></a> object(s).
</p>
<p>
- If a specific <a>search qualifier</a> element provided, or <code>filter[x]</code>, does not match any well-known <a
+ If a provided <a>search qualifier</a> element (<code>filter[x]</code>) does not match a <a
href="#contactproperties-interface"><code>ContactProperties</code></a> attribute, <code>filter[x]</code> SHOULD be ignored when
executing the current <a
href="#contacts-interface"><code>Contacts</code></a> <a
@@ -1490,7 +1439,7 @@
href="#contact-interface"><code>Contact</code></a> object. A lower value denotes a higher placing in the ultimate sorting of
<a
href="#contacts-interface"><code>Contacts</code></a> <a
- href="#widl-Contacts-find">find()</a> results. Search weights for each <a
+ href="#widl-Contacts-find">find()</a> results. The <dfn>search weights</dfn> for each <a
href="#contactproperties-interface"><code>ContactProperties</code></a> field are defined in <a
href="#search-weights">Appendix B</a>.
</p>
@@ -1520,20 +1469,27 @@
href="#widl-Contacts-find">find()</a> operation.
</p>
<p>
- A <a>search filter</a> is used to search all the fields of a <a
+ A <a>search filter</a> is used to search <a
+ href='#contactproperties-interface'><code>ContactProperties</code></a> within the <a
href="#contacts-interface"><code>Contacts</code></a> database and represents the logical union, or <code>∪</code>, of
provided values that are matched therein.
</p>
<p>
- All contact searching MUST apply a loose-matching policy to the <a>search filter</a> provided. If a <a
+ All contact searching MUST apply a <dfn>loose-matching policy</dfn> to the <a>search filter</a> provided. If a <a
href='#contactproperties-interface'><code>ContactProperties</code></a> attribute being searched in a <a
href='#contact-interface'><code>Contact</code></a> object, stored within the <a
- href='#contacts-interface'><code>Contacts</code></a> database, is a <a>partial value match</a> of the input filter value, that
+ href='#contacts-interface'><code>Contacts</code></a> database, is a <a>partial value match</a> of the input <code>filter</code> value, that
<a
href='#contact-interface'><code>Contact</code></a> object MUST be returned as part of the resulting <a
href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
</p>
<p>
+ A conforming implementation MUST only allow the provided <a>search filter</a> to be applied to fields requested in the provided <a>search qualifier</a>. The <code>id</code> attribute MUST always be implicitly searchable from any requesting web application regardless of whether it has been included as part of any provided <a>search qualifier</a>.
+ For example, if the given <a>search qualifier</a> contains 'name' and 'displayName', then the <a>rules for processing search filters</a> should only be applied to all sub-fields of the <code>name</code> attribute (i.e. <code>name.formatted</code>, <code>name.firstName</code>, <code>name.givenName</code>, <code>name.middleName</code>, <code>name.honorificPrefix</code>, <code>name.honorificSuffix</code>) and the <code>displayName</code> attribute.
+
+ </p>
+
+ <p>
A <dfn>partial value match</dfn> 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.
@@ -1705,13 +1661,22 @@
</p>
<ol>
<li>
- Using ECMA-262 3rd Edition regular expression syntax and psuedo-code, the <a>search filter</a> provided can be represented
- as:
+ Using ECMA-262 3rd Edition regular expression syntax and psuedo-code, the <a>search filter</a> provided can be represented as:
<pre>
- ( displayName = /∧.*Robert.*$/i ) ∪ ( name.formatted = /∧.*Robert.*$/i ) ∪ ( nickname = /∧.*Robert.*$/i )
- ∪ ( tags.value = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i ) ∪ ( addresses.formatted = /∧.*Robert.*$/i )
- ∪ ... etc for all contact attributes and properties ...
+( 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 )
</pre>
+ <br />
+ All searches are case-insensitive and apply a <a>loose-matching policy</a> as defined in <a href="#search-filters">Search Filters</a>.
+ Search ordering is sorted according to <a>search weights</a> defined in <a href="#search-filters">Search Filters</a> and described in <a href="#search-weights">Appendix B</a>.
+ <br /><br />
+ The <code>id</code> attribute is implicitly appended along with any <a>search filter</a> attributes provided, regardless of whether it was provided as a <a>search qualifier</a> from the requesting application, as defined in <a href="#search-filters">Search Filters</a>.
+ <br /><br />
+
</li>
<li>
Return only the valid <a
@@ -1780,11 +1745,10 @@
<p>
If an additional find(), save() or remove() 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 <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a>.
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a non-<code>null</code> <code>errorCB</code> parameter.
</p>
<p>
- If the user clicks 'Cancel', the <a
- href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> defined for the find() operation will be invoked with an error
+ If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be invoked with an error
code of <a
href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
</p>
@@ -1807,11 +1771,10 @@
<p>
If an additional find(), save() or remove() 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 <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a>.
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a non-<code>null</code> <code>errorCB</code> parameter.
</p>
<p>
- If the user clicks 'Cancel', the <a
- href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> associated to the current find() operation will be invoked with
+ If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be invoked with
an error code of <a
href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
</p>
@@ -2401,5 +2364,4 @@
<br>
</section>
</body>
-</html>
-
+</html>
\ No newline at end of file
Received on Monday, 5 July 2010 15:37:01 UTC