- From: Mercurial notifier <cvsmail@w3.org>
- Date: Fri, 22 Jun 2012 14:56:16 +0000
- To: public-dap-commits@w3.org
changeset: 118:28ce53656ad7
user: Robin Berjon <robin@berjon.com>
date: Fri Jun 22 16:35:38 2012 +0200
files: contacts/Overview.html
description:
removed search processing
diff -r d1d9a3a9b5e2 -r 28ce53656ad7 contacts/Overview.html
--- a/contacts/Overview.html Fri Jun 22 16:33:14 2012 +0200
+++ b/contacts/Overview.html Fri Jun 22 16:35:38 2012 +0200
@@ -777,175 +777,6 @@
</section>
<section>
- <h2><a>Contact Search Processing</a></h2>
-
- <p>
- The <a href="#contacts-interface"><code>Contacts</code></a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">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>
-
- <section>
- <h3>Search Qualifiers</h3>
-
- <p>
- The <dfn>search qualifier</dfn> provides an application with a way to request the specific subset of
- <a href="#contact-interface"><code>Contact</code></a> properties 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=
- "#contacts-interface"><code>Contacts</code></a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation as
- the <code>fields</code> parameter.
- </p>
-
- <p id="ta-aj" class="product-ua">
- A <a>search qualifier</a> MUST be specified from a requesting application as a part of any <a href=
- "#contacts-interface"><code>Contacts</code></a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- </p>
-
- <p id="ta-ab" class="product-ua">
- If the <a>search qualifier</a> provided is of <em>zero-length</em> then the current <a href=
- "#contacts-interface"><code>Contacts</code></a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation and
- the current find() operation was invoked with a non-<code>null</code>
- <code>errorCB</code> parameter, then the user agent MUST invoke the <code>errorCB</code> function
- with an error code of <a href=
- "#widl-ContactError-INVALID_ARGUMENT_ERROR"><code>INVALID_ARGUMENT_ERROR</code></a>.
- </p>
-
- <p id="ta-ak" class="product-ua">
- In the case that the <a>search qualifier</a> provided is of <em>non-zero-length</em> then the
- current <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation MUST return only the matching <a href=
- "#contact-interface"><code>Contact</code></a> properties within any resulting <a href=
- "#contact-interface"><code>Contact</code></a> object(s).
- </p>
-
- <p id="ta-al" class="product-ua">
- If a provided <a>search qualifier</a> element (<code>fields[x]</code>) does not match a <a href=
- "#contact-interface"><code>Contact</code></a> attribute, <code>fields[x]</code> SHOULD be ignored when
- executing the current <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- </p>
-
- <section>
- <h3>Advanced Search Qualifiers</h3>
-
- <p>
- We call <dfn>composed attributes</dfn> <a href="#contact-interface"><code>Contact</code></a>
- attributes of types <code>object</code>, which contain information only available
- only through child attributes of that object, or <code>array</code>.
- </p>
-
- <p class="product-ua" id="ta-ad">
- A requesting application MUST be able to request both the full composed <a href=
- "#contact-interface"><code>Contact</code></a> attribute and also be able to request individual parts
- of a composed <a href="#contact-interface"><code>Contact</code></a> attribute in the <a>search
- qualifier</a> provided to a <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- </p>
-
- <p>
- For example, the <code>name</code> attribute of a <a href=
- "#contact-interface"><code>Contact</code></a> object is defined to be of composed type <a href=
- "#contactname-interface"><code>ContactName</code></a>. Therefore, a requesting application may
- request either the full composed attribute (i.e. <code>name</code>) or specific individual attributes
- of this composed attribute (i.e. <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-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation's
- <a>search qualifier</a>.
- </p>
-
- <p id="ta-af" class="product-ua">
- In the case that a composed <a href="#contact-interface"><code>Contact</code></a> attribute is
- defined as an array of composed objects, specific individual attributes can be referenced
- by using the composed attribute name, a dot (<code>.</code>) character and the individual attribute
- to be retrieved.
- </p>
-
- <p>
- For example, the <code>addresses</code> attribute of <a href=
- "#contact-interface"><code>Contact</code></a> allows multiple <a href=
- "#contactaddress-interface"><code>ContactAddress</code></a> objects to be defined. To request
- individual attributes of this composed attribute an application would request e.g.
- <code>addresses.locality</code>, <code>addresses.region</code>, etc.
- </p>
- </section>
-
- <div class="example">
- <p>
- The following Contact search is initiated:
- </p>
- <pre class="sh_javascript">
-
- navigator.contacts( ['emails.value', 'name', 'friends'],
- function(contacts) {
- for(i in contacts) {
- for(j in contacts[i].emails)
- alert(contacts[i].emails[j]);
- }
- } );
- </pre>
-
- <p>
- The above example logically implies:
- </p>
-
- <ol class="rule">
- <li>Return only the valid <a href="#contact-interface"><code>Contact</code></a> attributes
- requested in the provided <a>search qualifier</a> (<code>name</code>, <code>emails.value</code> -
- <code>friends</code> is not a valid <a href="#contact-interface"><code>Contact</code></a> attribute
- so ignore this element).</li>
- </ol>
- </div>
- </section>
-
- <section>
- <h2>Options Processing</h2>
-
- <section>
- <h3>Search Cardinality</h3>
-
- <p id="ta-am" class="product-ua">
- By default, the <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">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="#contactfindcb-interface"><code>ContactFindCB</code></a> callback function.
- </p>
-
- <p id="ta-ae" class="product-ua">
- If a <a href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object is
- provided to the <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">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-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">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="#contactfindcb-interface"><code>ContactFindCB</code></a> callback function.
- </p>
- </section>
-
- <section>
- <h3>Search Filters</h3>
-
- <p>
- A <dfn>search filter</dfn> may be specified from a requesting web application to provide a hint to the user agents as to which contacts the user can select to share with the application.</p>
-
- <p>The <a>search filter</a> is defined through the <code>filter</code>
- attribute of the <a href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object
- provided to a <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- </p>
-
- <p>The actual usage of this <a>search filter</a> is user-agent dependant, but is expected to represent
- the logical union of provided values that are matched therein.
- </p>
- </section>
- </section>
- </section>
-
- <section>
<h2>Extended Contact Properties and Parameters</h2>
<p>
Received on Friday, 22 June 2012 14:56:22 UTC