W3C home > Mailing lists > Public > public-dap-commits@w3.org > June 2010

2009/dap/contacts Overview.html,1.59,1.60

From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 24 Jun 2010 09:08:03 +0000
To: public-dap-commits@w3.org
Message-Id: <E1ORiPj-0002UF-7r@lionel-hutz.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&#39;s
-        address book(s). All API methods disclose information related to a user&#39;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&#39;s privacy. A conforming implementation of this specification MUST provide a mechanism that protects the user&#39;s privacy
-        and this mechanism should ensure that no contact information is creatable, retrivable, updateable or removable without the
-        user&#39;s express permission.
+        The API defined in this specification can be used to create, find, save and remove contact information from a user&#39;s address
+        book(s). All API methods disclose information related to a user&#39;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&#39;s privacy.
+        A conforming implementation of this specification MUST provide a mechanism that protects the user&#39;s privacy and this mechanism
+        should ensure that no contact information is creatable, retrivable, updateable or removable without the user&#39;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&#39;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&#39;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&#39;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&#39;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&#39;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&#39;s <a>upper cardinality limit</a>. In this case <var>[X]</var> MUST be set
-            to the implementation&#39;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&#39;s <a>upper cardinality limit</a>. In this case <var>[X]</var> MUST be set to the
+            implementation&#39;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 &#39;Bob&#39; 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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 24 June 2010 09:08:06 GMT