This specification defines an API that provides scripted access to a calendar service of a device.
Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.
Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.
Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.
This section is non-normative.
The Calendar API defines a high-level interface to calendar information associated with the hosting device, such as meetings, reminders, anniversaries and todo items.
The following code extract illustrates how to work with a calendar service associated with the hosting device:
Example for instantiating a service object to access the device calendar.
// Loads an instance of a calendar interface identified by a service name
// "device", an interface name "calendar" and
// an interface version "1" or later.
var myCalendar = org.w3c.service.load("device", "calendar", "1");
NOTE: the namespace for the service interface loader is tentative.
Example of retrieving a list of calendar entries within a specified time range.
// Defines a callback function for getList().
// iterator - An iterator of calendar entries.
// status - An optional status code, non-zero values represent errors.
// transactionId - An optional unique identifier for the request.
function callback(iterator, status, transactionId) {
var calendarEntry, summaries;
if (status) {
alert("Error: " + status);
return;
}
while (calendarEntry = iterator.next()) {
summaries += calendarEntry.summary + "\n";
}
alert("Summaries:\n" + summaries);
}
// Specifies a matching filter for the calendar entries to return.
// In this example all entries of type "Meeting" beginning from the
// current date are matched.
var matchCriteria = { type: "Meeting",
range: { begin: new Date() }
};
var transactionId = myCalendar.getList(callback, matchCriteria);
Example of adding a calendar meeting entry.
// Sets the start year, month (0-11) and day (1-31) expressed in UTC time.
// In this example 2009-01-15 UTC (YYYY-MM-DD).
var startDate = new Date();
startDate.setUTCFullYear(2009, 0, 15);
// Sets the start hours (0-23), minutes (0-59) and seconds (0-59) expressed in UTC time.
// In this example 14:30:00 UTC (hh:mm:ss).
startDate.setUTCHours(14, 30, 0);
// Sets the end date similarly.
var endDate = new Date();
endDate.setUTCFullYear(2009, 0, 15);
endDate.setUTCHours(16, 0, 0);
// Adds a calendar entry of type "meeting" with a summary text "Review Meeting"
// to the calendar with the start and end dates specified by startDate and
// endDate respectively.
var myId = myCalendar.addEntry({ type: "meeting",
time: { start: startDate, end: endDate },
summary: "Review Meeting"
});
Example of updating a calendar entry.
var updatedEndDate = new Date();
updatedEndDate.setUTCFullYear(2009, 0, 15);
updatedEndDate.setUTCHours(17, 0, 0);
// Updates the end date of the calendar entry identified by myId.
myCalendar.updateEntry({ id: myId,
time: { end: updatedEndDate }
});
Example of deleting a calendar entry.
// Deletes the calendar entry identified by myId.
myCalendar.deleteEntry({ id: myId });
Example of cancelling the retrieval of calendar entries.
// Cancels the asynchronous getList() operation identified by transactionId.
myCalendar.cancel(transactionId);
This section is non-normative.
This specification is limited to [define scope].
To be written ...
The API defined in this specification [define security and privacy considerations].
This section is a placeholder for a set of recommendations addressed to the implementers of the Calendar API.
The key words must, must not, required, should, should not, recommended, may and optional in this specification are to be interpreted as described in [RFC2119].
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in [WebIDL].
The Calendar object can be used by
scripts to programmatically interact with the calendar of the hosting device.
interface Calendar {
int getList(in CalendarItemsCallback callback);
int getList(in CalendarItemsCallback callback, in MatchCriteria matchCriteria);
DOMString addEntry(in CalendarEntry calendarEntry);
void updateEntry(in CalendarEntry calendarEntry);
void deleteEntry(in DeleteCriteria deleteCriteria);
void cancel(in int transactionId);
};
interface CalendarItemsCallback {
void handleEvent(in CalendarIterator calendarIterator,
in int status,
in int transactionId);
};
The getList()
takes one or two arguments. When called it must immediately return a unique
transactionId. Next it must asynchronously retrieve a
CalendarIterator object
based on a specified MatchCriteria
object and invoke its associated callback argument with the
transactionId, the status and the
CalendarIterator object as
arguments. Non-zero values of the status attribute represent
error conditions. If the matchCriteria argument is null or
undefined then a
CalendarIterator object to all calendar entries will be returned.
Valid values for the status attribute must be defined.
The addEntry()
method takes a CalendarEntry
object as an argument and synchronously returns an id
of type DOMString which uniquely identifies the successfully
added calendar entry in the calendar database.
The updateEntry()
method takes a CalendarEntry object
identified by the unique identifier id.
If the calendar entry has multiple occurences ie. its
repeatRule is non-null, a particular
instance of a repeating calendar entry
to be updated is identified by its instanceStartTime.
The deleteEntry()
method takes a specified
DeleteCriteria object and removes qualified calendar entries from
the calendar database.
The cancel()
method takes a specified transactionId of type integer
which uniquely identifies the getList() process to be cancelled.
The transactionId is synchronously returned upon invocation of
the getList() method.
MatchCriteria
objects are regular ECMAScript objects that have the following properties:
interface MatchCriteria {
attribute DOMString id;
attribute Range range;
attribute DOMString type;
attribute DOMString text;
};
All the attributes in a MatchCriteria
object are optional.
The id
attribute is a unique identifier of a calendar entry in the calendar database. If
the id attribute is specified the
other attributes will be ignored.
The range
attribute is used to search for instances
which fall within the specified range. If unspecified then all
instances will be retrieved.
The type
attribute used to search only those calendar entries of the specified
type. If unspecified then all calendar entry types will be retrieved.
The text
attribute is used for text based search on
summary field of calendar
entries. Match algorithm is case insensitive.
CalendarEntry
objects are regular ECMAScript objects that have the following properties:
interface CalendarEntry {
attribute DOMString id;
attribute DOMString type;
attribute Time time;
attribute DOMString summary;
attribute RepeatRule repeatRule;
attribute DOMTimeStamp instanceStartTime;
attribute DOMString description;
attribute DOMString status;
attribute sequence<DOMTimeStamp> exceptionDates;
attribute DOMString location;
attribute int priority;
};
The optionality of the attributes in a
CalendarEntry object depends on the method which operates on the
object. When this object is passed to the
addEntry() method as an argument, the attributes
time and
summary are mandatory. For
the updateEntry() method the
attribute id is mandatory.
All the other attributes are optional.
The id
attribute is a unique identifier of a calendar entry in the calendar database.
The type
attribute represents calendar entry type defined in
calendar type constants.
The time
object represents start, end and alarm date of the calendar entry.
The summary
is a short summary or a subject of the calendary entry.
The repeatRule
object represents complete details of the repeat schedule applicable for the
calendar entry types meeting,
reminder, and
dayevent. This object is
optional for reminder
and dayevent types. This attribute
is optional.
The instanceStartTime
uniquely identifies a specific instance of a repeating calendar entry to be
operated on. This attribute must be defined if the
repeatRule attribute is
defined and is used by the
updateEntry() method only. This attribute is
optional.
The description
provides an optional complete description of the calendar
entry.
The status
property defines an optional status applicable to calendar
entry types meeting and
todo. Allowed values are
tentative (default), confirmed and
cancelled. The values are case-insensitive. This attribute is
optional.
The exceptionDates
contains a list of dates in the original repeat sequence that have been removed.
This attribute is optional.
The location
specifies an optional location applicable to entry type
meeting.
The priority
attribute defines an optional relative priority applicable for
todo entry type. Allowed value is an
integer from 0 (default) to 9.
Time
objects are regular ECMAScript objects that have the following properties:
interface Time {
attribute DOMTimeStamp start;
attribute DOMTimeStamp end;
attribute DOMTimeStamp alarm;
attribute DOMString alarmType;
};
All the attributes in a Time object
are optional.
The start
attribute represents the start time for the entry, applicable for
meeting,
anniversary,
reminder
and dayevent types.
The end
attribute represents the end time for the entry, applicable for
meeting and
todo types.
This attribute is optional for
dayevent type.
The alarm
attribute represents alarm time.
The alarmType
attribute takes values on or off for
Reminder type and
off, silent and audible
for all the other entry types. This attribute is
optional.
DeleteCriteria
objects are regular ECMAScript objects that have the following properties:
interface DeleteCriteria {
attribute DOMString id;
attribute Range range;
};
The id attribute
must always be specified. The optional
range attribute is used to
define a subset of instances in a calendar entry identified by the
id.
The id attribute is a unique
identifier of a specific CalendarEntry
object in the calendar database.
The range attribute
represents a Range
object which specifies the date range of instances to be operated on.
CalendarIterator
objects are regular ECMAScript objects that have the following properties:
interface CalendarIterator {
CalendarEntry next();
boolean hasNext();
};
The next()
method returns the next calendar entry item in the list. If the last calendar
entry in the list is reached the method will return null.
The hasNext()
method returns true if the next calendar entry exists.
Range
objects are regular ECMAScript objects that have the following properties:
interface Range {
attribute DOMTimeStamp begin;
attribute DOMTimeStamp end;
};
Either the begin or
end attribute
must be specified in a Range
object. If only the begin
attribute is specified the getList()
method retrieves all instances within or
after the specified date. Similarly, associated with a
DeleteCriteria
object passed to the
deleteEntry() method, all the instances
within or after the specified date will be deleted. If only the
end attribute is specified the
getList() method retrieves all
instances within or before the specified
date. Similarly, deleteEntry()
method will remove all the instances
within or before the specified date.
The begin
attribute represents the start time of range.
The end
attribute represents the end time of range.
RepeatRule
objects are regular ECMAScript objects that have the following properties:
interface RepeatRule {
attribute DOMString frequency;
attribute DOMTimeStamp startDate;
attribute DOMTimeStamp untilDate;
attribute int interval;
attribute sequence<int> weekDays;
attribute int month;
attribute sequence<DayOfMonth> daysOfMonth;
attribute sequence<int> monthDates;
};
All the attributes except the
frequency in a RepeatRule
object are optional.
The frequency
attribute specifies the repeat interval which must be one
of the following case insensitive values: daily,
weekly, monthly and yearly.
The startDate
attribute represents the date on which the repeat starts.
If this attribute is undefined the
start attribute will be used.
The untilDate
attribute represents the date on which this repeat rule finishes. If
the attribute is undefined the maximum date allowed by the implementation
is used.
The interval
attribute represents a positive integer defining how often the
recurrence rule must repeat. I.e. 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.
The weekDays
attribute represents on which days of the week the rule should repeat.
The attribute takes values 0 (Sunday) to 6 (Saturday) and is only applicable
for a weekly repeat. If this attribute is undefined the
start attribute will be used.
This attribute is optional.
The month
attribute represents the month for a yearly repeat rule. Takes values
0 (January) to 11 (December). If this attribute is undefined the
start attribute will be used.
This attribute is optional.
The daysOfMonth
attribute represents a list of
daysOfMonth objects which define the weekdays within a month the
rule should repeat. This parameter is applicable for monthly and
yearly repeats. For yearly repeat only the first
element is taken. If this attribute is undefined the
start attribute will be used.
This attribute is optional.
The monthDates
attribute represents on which dates of the month the rule should repeat.
Valid values are from 1 to 31. This parameter is applicable only for monthly
repeat. If this attribute is undefined the
start attribute will be used.
DayOfMonth
objects are regular ECMAScript objects that have the following properties:
interface DayOfMonth {
attribute int day;
attribute int weekInMonth;
};
Both the day and weekInMonth attributes are
optional.
The day
attribute specifies the weekday for the repeat. Weekday value of 0
denotes Sunday; 1 denotes Monday; 2 denotes Tuesday; 3 denotes
Wednesday; 4 denotes Thursday; 5 denotes Friday and 6 denotes
Saturday.
The weekInMonth
attribute represents the week number within the month. Valid values
are 1, 2, 3, 4 for the 1st, 2nd, 3rd and 4th week of the
month, or -1 for the last week of the month.
On error, the APIs throw DeviceException with an informative
error code. The DeviceException interface and error constants
are defined in Appendix A.
The type attribute in CalendarEntry
and MatchCriteria objects
should take one of the following case insensitive values of type DOMString:
meetingreminderdayeventtodoanniversary