- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 01 Feb 2010 12:44:20 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/calendar
In directory hutz:/tmp/cvs-serv30714
Modified Files:
Overview.html
Log Message:
2nd editor's draft of Calendar API
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/calendar/Overview.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- Overview.html 27 Jan 2010 10:29:36 -0000 1.11
+++ Overview.html 1 Feb 2010 12:44:18 -0000 1.12
@@ -79,8 +79,8 @@
}
// Perform a calendar search
-navigator.service.calendar.findEvents( {startBefore: 1270832400000}, // find all calendar events that start
- // before April 9, 2010 @ 5pm
+navigator.service.calendar.findEvents( {startBefore: '2010-04-10T05:00:00+12:00'}, // find all calendar events that start
+ // before April 9, 2010 @ 5pm (UTC)
successCalendarFindEventsCallback,
generalErrorCB );</pre>
</div>
@@ -95,16 +95,24 @@
description: 'W3C weekly meeting',
summary: 'Agenda to be distributed weekly',
location: 'IRC and Conf. call #XXX',
- start: 1264604400000, // January 27, 2010 @ 3pm
- end: 1264609800000, // January 27, 2010 @ 4:30pm
+ // Starts on January 27, 2010 @ 3pm (UTC):
+ start: '2010-01-27T10:00:00-05:00',
+ // Ends on January 27, 2010 @ 4:30pm (UTC):
+ end: '2010-01-27T11:30-05:00',
recurrence: {
- frequency: 'weekly',
- expires: 1312156800000, // August 1, 2011 @ 12am
- daysInWeek: [3] // Every Wednesday
+ frequency: 'weekly',
+ // Occurs every Wednesday:
+ daysInWeek: [3],
+ interval: 1,
+ // Event does not occur on December 22, 2010 and December 29, 2010
+ exceptionDates: ['2010-12-22', '2010-12-29'],
+ // Expires on or before August 1, 2011 @ Midnight (UTC):
+ expires: '2011-08-01T00:00:00Z'
},
- freebusy: 'busy',
+ transparency: 'transparent',
status: 'pending',
- reminder: -3600000, // Remind 1 hour before each occurrence of this event
+ // Remind 1 hour before each occurrence of this event:
+ reminder: '-3600000',
serviceId: 'http://localhost/calendar'
});</pre>
</div>
@@ -165,11 +173,12 @@
</p>
<p>
- This specification requires that UTC timestamp formatting for
- all dates and times be applied according to the defintion of DOMTimeStamp in [[!DOM-LEVEL-3-CORE]]. This is defined as the date and time, in
- milliseconds since the UNIX epoch (Jan 1, 1970). All UTC timestamps must be normalized to standard GMT +0 times. This specification is not
- prescriptive on the way that date and time information should be rendered according to any specific time zone, only that the any dates and times
- provided have been normalized to a standard time zone by the API for the purposes of distribution across heterogeneous clients.
+ This specification requires that formatting for
+ all dates and times be applied according to the defintion of <dfn id="dfn-valid-date-or-time-string">valid date and time string</dfn> in [[!HTML5]].
+ </p>
+
+ <p class='note'>
+ See: <a href="http://dev.w3.org/html5/spec/Overview.html#valid-date-or-time-string">http://dev.w3.org/html5/spec/Overview.html#valid-date-or-time-string</a>
</p>
</section
@@ -365,7 +374,7 @@
Function to call when the asynchronous operation fails.
</dd>
<dt>
- optional CalendarOptions options
+ optional CalendarFindOptions options
</dt>
<dd>
The options to apply to the output of this method.
@@ -388,9 +397,6 @@
<p>A globally unique identifier for the given <code>CalendarEvent</code> object. Each <code>CalendarEvent</code> referenced from <code>Calendar</code> MUST include a non-empty <code>id</code> value.</p>
<p>An implementation MUST maintain this globally unique resource identifier when a calendar event is added to, or present within, a Calendar.</p>
<p>An implementation MAY use an IANA registered identifier format. The value can also be a non-standard format.</p>
- <p>It is RECOMMENDED that an implementation assign the id attribute as a <abbr name="Universally Unique IDentifier">UUID</abbr> URN as defined in [[RFC4122]].</p>
-
- <pre class="example sh_javascript">{id: 'urn:uuid:3a100df9c-e900-9dab-47f1-9fb99932cb88'}</pre>
</dd>
<dt>
CalendarEvent clone ()
@@ -523,20 +529,20 @@
<pre class="example sh_javascript_dom">{summary: 'Agenda:\n\n\t* Introductions\n\t* AoB'}</pre>
</dd>
<dt>
- attribute DOMTimeStamp start
+ attribute DOMString start
</dt>
<dd>
- <p>The start date and time of the event in UTC timestamp format as defined in [[!DOM-LEVEL-3-CORE]].</p>
+ <p>The start date and time of the event as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>.</p>
- <pre class="example sh_javascript_dom">{start: 1269439200000} // Event starts on March 24, 2010 @ 2pm</pre>
+ <pre class="example sh_javascript_dom">{start: '2010-03-24T09:00-08:00'} // Event starts on March 24, 2010 @ 5pm (UTC)</pre>
</dd>
<dt>
- attribute DOMTimeStamp? end
+ attribute DOMString? end
</dt>
<dd>
- <p>The end date and time of the event in UTC timestamp format as defined in [[!DOM-LEVEL-3-CORE]].</p>
+ <p>The end date and time of the event as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>.</p>
- <pre class="example sh_javascript_dom">{end: 1269442800000} // Event ends on March 24, 2010 @ 3pm</pre>
+ <pre class="example sh_javascript_dom">{end: '2010-03-24T10:00:00-08:00'} // Event ends on March 24, 2010 @ 6pm (UTC)</pre>
</dd>
<dt>
attribute DOMString? status
@@ -550,15 +556,15 @@
<pre class="example sh_javascript_dom">{status: 'pending'} // Event is awaiting user action</pre>
</dd>
<dt>
- attribute DOMString? freebusy
+ attribute DOMString? transparency
</dt>
<dd>
- <p>An indication of the freebusy status to set for the event.
+ <p>An indication of the display status to set for the event.
<p>This parameter may be set to one of the following constants:</p>
- <pre>'free', 'busy', 'outofoffice', 'holiday'.</pre>
+ <pre>'transparent', 'opaque'.</pre>
- <pre class="example sh_javascript_dom">{freebusy: 'busy'} // Mark event as busy in Calendar</pre>
+ <pre class="example sh_javascript_dom">{freebusy: 'transparent'} // Mark event as transparent in Calendar</pre>
</dd>
<dt>
attribute CalendarRepeatRule? recurrence
@@ -566,54 +572,54 @@
<dd>
<p>The recurrence or repetition rule for this event
- <pre class="example sh_javascript">{recurrence: {frequency: 'daily'}} // Event occurs every day and never expires</pre>
+ <pre class="example sh_javascript">{recurrence: {frequency: 'daily'}} // Event occurs every day and never expires</pre>
- <pre class="example sh_javascript">{recurrence: {frequency: 'weekly', // Event occurs weekly...
+ <pre class="example sh_javascript">{recurrence: {frequency: 'weekly', // Event occurs weekly...
daysInWeek: [2, 4], // ...every Tuesday and Thursday
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm</pre>
+ expires: '2010-06-11T12:00:00-04:00'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'weekly', // Event occurs weekly...on every Wednesday
// (if we say the 'start' attribute is March 24, 2010 @ 2pm (Wednesday) as
// shown above and no daysInWeek attribute is provided)
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm </pre>
+ expires: '2010-06-11T11:00:00-05:00'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'monthly', // Event occurs monthly...
daysInMonth: [-5], // ...5 days before the end of each month
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm</pre>
+ expires: '2010-06-11T20:00:00+04:00'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'monthly', // Event occurs monthly...on the 24th day of every month
// (if we say the 'start' attribute is March 24, 2010 @ 2pm as
// shown above and no daysInMonth attribute is provided)
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm </pre>
+ expires: '2010-06-11T20:00:00+04:00'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'yearly', // Event occurs yearly...on the 24th day of every March
// (if we say the 'start' attribute is March 24, 2010 @ 2pm as
// shown above and no daysInMonth attribute is provided)
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm </pre>
+ expires: '2010-06-11T16:00:00+00:00'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'yearly', // Event occurs yearly...
daysInMonth: [24], // ...every 24th day...
monthsInYear: [3, 6], // ...in every March and June
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm </pre>
+ expires: '2010-06-11T16:00:00Z'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
<pre class="example sh_javascript">{recurrence: {frequency: 'yearly', // Event occurs yearly...
daysInYear: [168], // ...every 168th day of each year
- expires: 1276272000000}} // Event expires on or before June 11, 2010 @ 4pm </pre>
+ expires: '2010-06-11T21:45:00+05:45'}} // Event expires on or before June 11, 2010 @ 4pm (UTC)</pre>
</dd>
<dt>
- attribute long long? reminder
+ attribute DOMString? reminder
</dt>
<dd>
<p>A reminder for the event.</p>
- <p>This attribute can be specified as a positive value in standard UTC timestamp format, as defined in [[!DOM-LEVEL-3-CORE]], denoting a one-time reminder or as a negative value in milliseconds denoting a relative relationship
+ <p>This attribute can be specified as a positive <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>.</p>, denoting a one-time reminder or as a negative value in milliseconds denoting a relative relationship
to the start time of the calendar event.</p>
- <p>A relative reminder is paticularly useful for setting a reminder for recurring events.</p>
+ <p>A relative reminder is recommended for setting a reminder for recurrent events.</p>
- <pre class="example sh_javascript_dom">{reminder: 1269435600000} // Remind ONCE on March 24, 2010 @ 1pm</pre>
- <pre class="example sh_javascript_dom">{reminder: -3600000} // Remind 1 hour before every occurrence of this event</pre>
+ <pre class="example sh_javascript_dom">{reminder: '2010-03-24T13:00:00+00:00'} // Remind ONCE on March 24, 2010 @ 1pm (UTC)</pre>
+ <pre class="example sh_javascript_dom">{reminder: '-3600000'} // Remind 1 hour before every occurrence of this event</pre>
</dd>
<dt>
@@ -638,28 +644,28 @@
<dl title='[NoInterfaceObject] interface CalendarFindEventProperties : CalendarEventProperties' class='idl'>
<dt>
- attribute DOMTimeStamp startBefore
+ attribute DOMString startBefore
</dt>
<dd>
- Search for Calendar Events that start before the UTC time provided as defined in [[!DOM-LEVEL-3-CORE]].
+ Search for Calendar Events that start before the time provided as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>..
</dd>
<dt>
- attribute DOMTimeStamp startAfter
+ attribute DOMString startAfter
</dt>
<dd>
- Search for Calendar Events that start after the UTC time provided as defined in [[!DOM-LEVEL-3-CORE]].
+ Search for Calendar Events that start after the time provided as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>..
</dd>
<dt>
- attribute DOMTimeStamp endBefore
+ attribute DOMString endBefore
</dt>
<dd>
- Search for Calendar Events that end before the UTC time provided as defined in [[!DOM-LEVEL-3-CORE]].
+ Search for Calendar Events that end before the time provided as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>..
</dd>
<dt>
- attribute DOMTimeStamp endAfter
+ attribute DOMString endAfter
</dt>
<dd>
- Search for Calendar Events that end after the UTC time provided as defined in [[!DOM-LEVEL-3-CORE]].
+ Search for Calendar Events that end after the time provided as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>..
</dd>
</dl>
</section>
@@ -685,14 +691,38 @@
<pre class="example sh_javascript_dom">{frequency: 'monthly'} // Event repeats on a monthly basis</pre>
</dd>
<dt>
- attribute DOMTimeStamp? expires
+ attribute unsigned short? interval
</dt>
<dd>
- <p>The date and time to which the CalendarRepeatRule applies in DOMTimeStamp format as defined in [[!DOM-LEVEL-3-CORE]].</p>
+ <p>A positive integer defining how often the recurrence rule MUST repeat.</p>
+
+ <p>
+ For interval N, recurrence rule repeats every Nth frequency. Default interval value is 1, that is every day for a daily, every week for a weekly, every month for a monthly and every year for a yearly.
+ </p>
+
+ <p>If this parameter is set to <code>null</code> the event item does not have any fixed interval and the event interal should be derived from the other <code>CalendarRepeatRule</code> attributes.</p>
+
+ <pre class="example sh_javascript_dom">{interval: 1}</pre>
+ </dd>
+ <dt>
+ attribute DOMString? expires
+ </dt>
+ <dd>
+ <p>The date and time to which the CalendarRepeatRule applies as a <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a>.</p>
<p>If this parameter is set to <code>null</code> the event item does not have any fixed expiry date and the event is scheduled to continue indefintely.</p>
- <pre class="example sh_javascript_dom">{expires: 1312156800000} // Event repeats until August 1, 2011 @ 12am</pre>
+ <pre class="example sh_javascript_dom">{expires: '2011-08-01T01:00:00+01:00'} // Event repeats until August 1, 2011 @ 12am (UTC)</pre>
+ </dd>
+ <dt>
+ attribute DOMString[] exceptionDates
+ </dt>
+ <dd>
+ <p>One or more dates and times to which the CalendarRepeatRule does not apply as <a href="#dfn-valid-date-or-time-string" class="internalDFN">valid date or time string</a> strings.</p>
+
+ <p>If this parameter is set to <code>null</code> the event item does not have any exception dates and/or times.</p>
+
+ <pre class="example sh_javascript_dom">{exceptionDates: ['2010-12-22', '2010-12-29']} // Event does not occur on December 22, 2010 and December 29, 2010</pre>
</dd>
<dt>
attribute short[] daysInWeek
@@ -798,16 +828,13 @@
</section>
<section>
- <h2><a>CalendarOptions</a> interface</h2>
- <p class='note'>
- Rename this to "CalendarSearchFilter" or similar?
- </p>
+ <h2><a>CalendarFindOptions</a> interface</h2>
<p>
- The <a href='#calendaroptions-interface'><code>CalendarOptions</code></a>
+ The <a href='#calendaroptions-interface'><code>CalendarFindOptions</code></a>
interface describes the options that can be applied to calendar searching.
</p>
- <dl title='[NoInterfaceObject] interface CalendarOptions' class='idl'>
+ <dl title='[NoInterfaceObject] interface CalendarFindOptions' class='idl'>
<dt>
attribute unsigned short limit
</dt>
@@ -1043,7 +1070,7 @@
<p>
For example, the following <a href="#calendarfindeventproperties-interface"><code>CalendarFindEventProperties</code></a> object is supplied for Calendar Event searching:
<pre class="example sh_javascript">navigator.service.calendar.findEvents({
- startBefore: 1282780800000, // All events before August 26, 2010
+ startBefore: '2010-08-26', // All events before August 26, 2010
freebusy: 'busy'
},
/*...*/);</pre>
Received on Monday, 1 February 2010 12:44:22 UTC