- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 07 Mar 2011 17:18:13 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv21184/contacts
Modified Files:
Overview.html
Log Message:
Updated specification in line with feedback to date:
- Contact.timezone field now recommends the use of timezone identifiers.
- PendingOp removed from spec (see: Minutes 9th Feb 2011)
- Interfaces rebased on to navigator object (see: Minutes 9th Feb 2011)
- Changed contacts event task source to generic 'device task source'
- Fixed typo in section 5.1: http://lists.w3.org/Archives/Public/public-device-apis/2011Mar/0013.html
- Updated examples according to changes
- Added IDL wrapping CSS fix
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.113
retrieving revision 1.114
diff -u -d -r1.113 -r1.114
--- Overview.html 21 Jan 2011 01:51:43 -0000 1.113
+++ Overview.html 7 Mar 2011 17:18:11 -0000 1.114
@@ -29,6 +29,9 @@
previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/",
// lcEnd: "2009-08-05",
+ preProcess: [function() {
+ berjon.biblio["TZDB"] = '<a href="http://www.twinsun.com/tz/tz-link.htm">Time Zone Information Database</a>. Available at <a href="http://www.twinsun.com/tz/tz-link.htm">http://www.twinsun.com/tz/tz-link.htm</a>';
+ }]
};
</script>
<script
@@ -81,6 +84,20 @@
ol.rule li, ul.rule li {
padding:0.2em;
}
+/*
+IDL wrapping fix
+http://perishablepress.com/press/2010/06/01/wrapping-content/
+*/
+pre {
+ white-space: pre; /* CSS 2.0 */
+ white-space: pre-wrap; /* CSS 2.1 */
+ white-space: pre-line; /* CSS 3.0 */
+ white-space: -pre-wrap; /* Opera 4-6 */
+ white-space: -o-pre-wrap; /* Opera 7 */
+ white-space: -moz-pre-wrap; /* Mozilla */
+ white-space: -hp-pre-wrap; /* HP Printers */
+ word-wrap: break-word; /* IE 5+ */
+}
</style>
</head>
<body>
@@ -162,12 +179,11 @@
// Perform an address book search. Obtain the 'name' and 'emails' properties
// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
- successContactFindCallback,
- generalErrorCB,
- {filter: 'Bob'}
- );
-// ..is equivalent to: navigator.service.contacts(/* parameters */)
+navigator.contacts.find( ['name', 'emails'],
+ successContactFindCallback,
+ generalErrorCB,
+ {filter: 'Bob'} );
+// ..is equivalent to: navigator.contacts(/* parameters */)
</pre>
</div>
</section>
@@ -195,12 +211,7 @@
source</dfn> and <dfn>task queues</dfn> are defined by the HTML5 specification [[!HTML5]].
</p>
<p>
- The <a>task source</a> used by this specification is the <dfn><a
- href="http://dev.w3.org/2009/dap/device/#the-pendingop-interface">PendingOp</a> task source</dfn>.
- </p>
-
- <p class="issue">
- PendingOp needs updating in [[!CORE-DEVICE]] to show that it is a valid <a>task source</a>.
+ The <a>task source</a> used by this specification is the <dfn>device task source</dfn>.
</p>
<p>
To <dfn>dispatch a <code>success</code> event</dfn> means that an event with the name <code>success</code>, which does
@@ -320,14 +331,9 @@
</h2>
<p>
The <a
- href='#servicecontacts-interface'><code>ServiceContacts</code></a> interface is exposed on the <code>navigator.service</code>
- object, as defined in [[!CORE-DEVICE]].
+ href='#servicecontacts-interface'><code>ServiceContacts</code></a> interface is exposed on the <a class="externalDFN" href="http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a>
+ interface [[HTML5].
</p>
- <div
- class='idl'
- title='Service implements ServiceContacts'>
-
- </div>
<dl
title='[NoInterfaceObject] interface ServiceContacts'
class='idl'>
@@ -338,6 +344,11 @@
The root node from which the contacts functionality can be accessed.
</dd>
</dl>
+ <div
+ class='idl'
+ title='Navigator implements ServiceContacts'>
+
+ </div>
</section>
<section>
<h2>
@@ -358,21 +369,19 @@
title='[NoInterfaceObject] interface Contacts'
class='idl'>
<dt>
- caller PendingOp find ()
+ caller void find ()
</dt>
<dd>
<p>
Find contacts in the address book according to the <a>find contacts process</a> detailed below.
</p>
<p>
- This method takes two, three or four arguments. When called, it immediately returns a <code>PendingOp</code> object, as
- defined in [[!CORE-DEVICE]], and then asynchronously starts a <dfn>find contacts process</dfn> defined as follows:
+ This method takes two, three or four arguments. When called, it immediately returns and then asynchronously starts a <dfn>find contacts process</dfn> defined as follows:
</p>
<ol
class="rule">
<li>
- If there are any <a>tasks</a> from the <a
- title="PendingOp task source"><code>PendingOp</code> task source</a> in one of the <a>task queues</a>
+ If there are any <a>tasks</a> from the <a>device task source</a> in one of the <a>task queues</a>
(i.e. an existing <code>find()</code> operation is still pending a response), and the current method was invoked with a
non-<code>null</code> <code>errorCB</code> argument, <a>dispatch an <code>error</code> event</a> with a <a
href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> <code>code</code> value.
@@ -620,15 +629,24 @@
</dt>
<dd>
<p>
- The value contains the time zone of this Contact as an offset from UTC.
+ This attribute represents the time zone of this Contact.
</p>
- <p>
- The value MUST be specified as a positive or negative difference
- from the UTC in units of hours and minutes (i.e. <code>+hh:mm</code>). Example, by specifying <code>+05:30</code> indicates the Contact
- is associated with a current time zone of GMT+05:30.
+ <p>
+ It is RECOMMENDED that names from the public-domain
+ Olson database [[TZDB]] will be used as the value of this attribute, but this is not a restriction. For example, a value of <code>America/New_York</code> indicates the Contact
+ is associated with the variable time zone of the New York region of the United States, including daylight saving time offsets experienced in that region.
+ </p>
+ <p>
+ It is also possible to use this attribute to express the timezone as a positive or negative difference
+ from UTC, in the 24-hour clock, in units of hours and minutes (i.e. <code>+hh:mm</code>). For example, a value of <code>+05:30</code> indicates the Contact
+ is associated with a fixed time zone of GMT+05:30.
</p>
<p class="note">
- This value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.
+ Where possible UTC offset values SHOULD NOT be used. The UTC
+ offset varies with time - not just because of the usual daylight
+ saving time shifts that occur in may regions, but often entire
+ regions will "re-base" their overall offset. The actual offset
+ may be +/- 1 hour (or perhaps a little more) than any UTC offset given.
</p>
</dd>
</dl>
@@ -894,7 +912,7 @@
<a>ContactFindCB</a> interface
</h2>
<dl
- title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindCB : PendingOp'
+ title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindCB'
class='idl'>
<dt>
void onsuccess ()
@@ -956,7 +974,7 @@
</h2>
<!-- interface intro here -->
<dl
- title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB : PendingOp'
+ title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB'
class='idl'>
<dt>
void onerror ()
@@ -1093,7 +1111,7 @@
<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">find()</a> operation as the <code>filter</code> parameter.
+ href="#widl-Contacts-find">find()</a> operation as the <code>fields</code> parameter.
</p>
<p>
A <a>search qualifier</a> MUST be specified from a requesting application as a part of any <a
@@ -1168,13 +1186,13 @@
<pre
class="sh_javascript">
- navigator.service.contacts.find(['emails.value', 'name', 'friends'],
- function(contacts) {
- for(i in contacts) {
- for(j in contacts[i].emails)
- alert(contacts[i].emails[j]);
- }
- });
+ 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:
@@ -1404,13 +1422,11 @@
</p>
<pre
class="sh_javascript">
- navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
- function(contacts) {
- for(x in contacts) alert(contacts[x].name);
- },
- {
- filter: 'Robert'
- });
+ navigator.contacts( ['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
+ function(contacts) {
+ for(x in contacts) alert(contacts[x].name);
+ },
+ { filter: 'Robert' } );
</pre>
<p>
@@ -1636,7 +1652,7 @@
// Perform an address book search. Obtain the 'name' and 'emails' properties
// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
+navigator.contacts.find(['name', 'emails'],
successContactFindCallback,
generalErrorCB,
{filter: 'Bob'}
@@ -1736,11 +1752,11 @@
function getContacts() {
// Perform an address book search. Obtain the 'name' and 'emails' properties
// and initially filter the list to Contact records containing 'Bob':
- navigator.service.contacts.find(['name', 'emails'],
- successContactFindCallback,
- generalErrorCB,
- {filter: 'Bob'}
- );
+ navigator.contacts( ['name', 'emails'],
+ successContactFindCallback,
+ generalErrorCB,
+ { filter: 'Bob' } );
+ // is equivalent to: navigator.contacts.find(/* parameters */);
}
</script>
</pre>
@@ -1954,7 +1970,7 @@
<pre class="sh_javascript"><a id="vcard">Save our Contact Details</a>
<script type="text/javascript">
- // Obtain a single existing Contact object resulting from navigator.service.contacts.find()
+ // Obtain a single existing Contact object resulting from navigator.contacts.find()
var existingContactObj = ...;
var vcard = 'BEGIN:VCARD\r\n' +
@@ -1975,7 +1991,7 @@
<pre class="sh_javascript"><a id="vcard">Update our Contact Details</a>
<script type="text/javascript">
- // Obtain a single existing Contact object resulting from navigator.service.contacts.find()
+ // Obtain a single existing Contact object resulting from navigator.contacts.find()
var existingContactObj = ...;
// Modify some parameters as required. e.g. add a new phone number
Received on Monday, 7 March 2011 17:18:15 UTC