Calendar API

The Calendar API provides interfaces and methods for users to manage their schedule. Separate calendars can be implemented for group related events or tasks. For example, a user may have a work, personal, and family calendar. A calendar entry is called an event and is composed of a series of attributes, such as purpose, starting time, and duration. A calendar is a collection of events.

The Internet Calendaring and Scheduling Core Object Specification (iCalendar), defines a format for exchanging event items. Mapping to specified event/task attributes in this API is as per this specification. For details, see RFC 5545.

This API provides functionality to read, create, delete, and update items in specific calendars. Calendars can be obtained using the getCalendars() method, which returns an array of Calendar objects.

For more information on the Calendar features, see Calendar Guide.

Since: 1.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
CalendarManagerObject
CalendarManager
void getCalendars (CalendarType type, CalendarArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
void addCalendar (Calendar calendar)
Calendar
void add (CalendarItem item)
void addBatch (CalendarItem[] items, optional CalendarItemArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void update (CalendarItem item, optional boolean? updateAllInstances)
void updateBatch (CalendarItem[] items, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional boolean? updateAllInstances)
void removeBatch (CalendarItemId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void find (CalendarItemArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode)
void removeChangeListener (long watchId)
CalendarItemInit
CalendarTaskInit
CalendarEventInit
CalendarItem
CalendarTask
CalendarEvent
void expandRecurrence (TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
CalendarAttendeeInit
CalendarAttendee
CalendarRecurrenceRuleInit
CalendarRecurrenceRule
CalendarEventId
CalendarAlarm
CalendarEventArraySuccessCallback
void onsuccess (CalendarEvent[] events)
CalendarItemArraySuccessCallback
void onsuccess (CalendarItem[] items)
CalendarArraySuccessCallback
void onsuccess (Calendar[] calendars)
CalendarChangeCallback
void onitemsadded (CalendarItem[] items)

1. Type Definitions

1.1. CalendarId

The calendar identifier.
  typedef DOMString CalendarId;

Since: 1.0

1.2. CalendarTaskId

The calendar task identifier.
  typedef DOMString CalendarTaskId;

Since: 1.0

1.3. CalendarItemId

The calendar item identifier, which can either be a CalendarEventId or a CalendarTaskId.
  typedef (CalendarEventId or CalendarTaskId) CalendarItemId;

Since: 1.0

1.4. CalendarType

Specifies the calendar types.
  enum CalendarType { "EVENT", "TASK" };

Since: 1.0

The following types are supported:

  • EVENT - if a calendar contains events (VEVENT objects)
  • TASK - if a calendar contains tasks (VTODO objects)

1.5. CalendarTextFormat

Specifies the types of textual format of a Calendar.
  enum CalendarTextFormat { "ICALENDAR_20", "VCALENDAR_10" };

Since: 1.0

The following values are supported:

  • ICALENDAR_20 - if the textual format is iCalendar v2.0
  • VCALENDAR_10 - if the textual format is vCalendar v1.0

1.6. AlarmMethod

Specifies the alarm types.
  enum AlarmMethod { "SOUND", "DISPLAY" };

Since: 1.0

The following values are supported:

  • SOUND - if sound is played to alert the user
  • DISPLAY - if display on screen without any sound is used to alert the user

1.7. RecurrenceRuleFrequency

Specifies the types of frequency for the recurrence of an event.
  enum RecurrenceRuleFrequency { "DAILY", "WEEKLY", "MONTHLY", "YEARLY" };

Since: 1.0

Only the following values are valid for this attribute:

  • DAILY - if the event occurs daily
  • WEEKLY - if the event occurs weekly
  • MONTHLY - if the event occurs monthly
  • YEARLY - if the event occurs yearly

1.8. ByDayValue

Specifies the values for CalendarRecurrenceRule.daysOfWeek.
  enum ByDayValue { "MO", "TU", "WE", "TH", "FR", "SA", "SU" };

Since: 1.0

  • "MO" corresponds to "Monday"
  • "TU" corresponds to "Tuesday"
  • "WE" corresponds to "Wednesday"
  • "TH" corresponds to "Thursday"
  • "FR" corresponds to "Friday"
  • "SA" corresponds to "Saturday"
  • "SU" corresponds to "Sunday"

1.9. EventAvailability

Specifies the availability types of time for an event.
  enum EventAvailability { "BUSY", "FREE", "BUSY_UNAVAILABLE", "BUSY_TENTATIVE" };

Since: 1.0

The following values are supported:

  • FREE - if the specified time slot is vacant
  • BUSY - if the specified time slot is not vacant
  • BUSY_UNAVAILABLE - if the specified time slot is not vacant and can not be scheduled
  • BUSY_TENTATIVE - if the specified time slot is not vacant because one or more events have been tentatively scheduled for that interval

Remark: BUSY_UNAVAILABLE and BUSY_TENTATIVE are supported since Tizen 5.0

1.10. AttendeeType

Specifies the types of attendee.
  enum AttendeeType { "INDIVIDUAL", "GROUP", "RESOURCE", "ROOM", "UNKNOWN" };

Since: 1.0

At least the following values must be supported:

  • INDIVIDUAL - Individual
  • GROUP - Group of individuals
  • RESOURCE - Physical resource
  • ROOM - Room resource
  • UNKNOWN - Unknown

1.11. AttendeeStatus

Specifies the attendance status types of a participant.
  enum AttendeeStatus { "PENDING", "ACCEPTED", "DECLINED", "TENTATIVE", "DELEGATED", "COMPLETED", "IN_PROCESS" };

Since: 1.0

At least the following values must be supported:

  • PENDING - if the participant has not yet responded to the event
  • ACCEPTED - if the participant has accepted the event
  • DECLINED - if the participant has declined the event
  • TENTATIVE - if the participant has tentatively accepted the event
  • DELEGATED - if the participant has delegated attendance to another participant
  • COMPLETED - if the participant's event has been completed
  • IN_PROCESS - if the participant's event is currently in process

1.12. AttendeeRole

Specifies the role of an attendee.
  enum AttendeeRole { "REQ_PARTICIPANT", "OPT_PARTICIPANT", "NON_PARTICIPANT", "CHAIR" };

Since: 1.0

At least the following values must be supported:

  • REQ_PARTICIPANT - if the participation of an attendee is mandatory
  • OPT_PARTICIPANT - if the participation of an attendee is optional
  • NON_PARTICIPANT - if the attendee is not a participant but is copied for information purposes
  • CHAIR - if the attendee is the chairperson of the event.

1.13. CalendarItemPriority

Specifies the priority of a calendar item.
  enum CalendarItemPriority { "HIGH", "MEDIUM", "LOW", "NONE" };

Since: 1.0

The following values are supported:

  • HIGH - if item priority is high
  • MEDIUM - if item priority is medium
  • LOW - if item priority is low
  • NONE - if item priority is not set

1.14. CalendarItemVisibility

Specifies the visibility types of a calendar item.
  enum CalendarItemVisibility { "PUBLIC", "PRIVATE", "CONFIDENTIAL" };

Since: 1.0

The following values are supported:

  • PUBLIC - if item visibility is public
  • PRIVATE - if item visibility is private
  • CONFIDENTIAL - if item visibility is confidential

1.15. CalendarItemStatus

Specifies the status of a calendar item.
  enum CalendarItemStatus { "NONE", "TENTATIVE", "CONFIRMED", "CANCELLED", "NEEDS_ACTION", "IN_PROCESS", "COMPLETED" };

Since: 1.0

For an event, the possible values are:

  • NONE - if the status for the event is not set
  • TENTATIVE - if the event is tentative
  • CONFIRMED - if the event is confirmed
  • CANCELLED - if the event is cancelled

For a task, the possible values are:

  • NONE - if the status for the task is not set
  • NEEDS_ACTION - if the task needs action
  • IN_PROCESS - if the task is in process or being worked on
  • COMPLETED - if the task has been completed
  • CANCELLED - if the task has been cancelled

2. Interfaces

2.1. CalendarManagerObject

The CalendarManagerObject interface gives access to the Calendar API from the tizen.calendar object.
  [NoInterfaceObject] interface CalendarManagerObject {
    readonly attribute CalendarManager calendar;
  };
  Tizen implements CalendarManagerObject;

Since: 1.0

Attributes

  • readonly CalendarManager calendar
    Object representing a calendar manager.

    Since: 1.0

2.2. CalendarManager

The CalendarManager interface provides methods to access calendars and attributes for calendars. Once a calendar object is obtained, it is possible to add, remove, or update the information it contains through the Calendar interface methods.
  [NoInterfaceObject] interface CalendarManager {
    void getCalendars(CalendarType type, CalendarArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                      raises(WebAPIException);
    Calendar getUnifiedCalendar(CalendarType type) raises(WebAPIException);
    Calendar getDefaultCalendar(CalendarType type) raises(WebAPIException);
    void addCalendar(Calendar calendar) raises(WebAPIException);
    void removeCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
    Calendar getCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
  };

Since: 1.0

Methods

getCalendars
Gets an array of Calendar objects.
void getCalendars(CalendarType type, CalendarArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

If the operation completes successfully, the successCallback() must be invoked with all the calendars found and available. The first calendar in the list is always the default calendar.

If no Calendar object is available, the successCallback() is invoked with an empty array.

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if any of the input parameters contain an invalid value.
  • UnknownError - if any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • type: Type of a calendar.
  • successCallback: Callback method that is invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

var calendar;

function eventFoundCallback(events)
{
  /* Event has been successfully found. */
  /* Changes the summary. */
  events[0].summary = "HTML6 Webinar";
  calendar.update(events[0]);
  console.log("First event was updated!");
}

/* Defines the error callback for all the asynchronous calls. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the success callback for retrieving the list of calendars. */
function calendarListCallback(calendars)
{
  if (calendars.length > 0)
  {
    calendar = calendars[0];
    console.log("The calendar id is " + calendar.id + " and name " + calendar.name);

    var ev = new tizen.CalendarEvent(
    {
      description: "HTML5 Introduction",
      summary: "HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      duration: new tizen.TimeDuration(1, "HOURS"),
      location: "Huesca"
    });
    calendar.add(ev);

    /* Event has been successfully added. */
    /* Checks whether the added event can be retrieved from the calendar. */
    /* If the calendar was empty, only the item added through add() should be returned. */
    var filter = new tizen.AttributeFilter("summary", "CONTAINS", "HTML5");
    calendar.find(eventFoundCallback, errorCallback, filter);
  }
}

/* Gets a list of available calendars. */
tizen.calendar.getCalendars("EVENT", calendarListCallback, errorCallback);
getUnifiedCalendar
The unified calendar is the aggregation of all calendars that are obtained from getCalendars and contains all events or tasks. It does not have the calendar ID nor name which are set to null.
Calendar getUnifiedCalendar(CalendarType type);

Since: 2.1

If an item is added to the unified calendar, it will be saved in the default calendar.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • type: Type of a calendar.

Return value:

    Calendar: The unified Calendar object.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var unifiedCalendar;

/* Defines the error callback for all the asynchronous calls. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

function eventFoundCallback(events)
{
  /* Event has been successfully found. */
  /* Changes the summary. */
  events[0].summary = "HTML6 Webinar";
  unifiedCalendar.update(events[0]);
  console.log("First event was updated!");
}

/* Gets the unified calendar. */
unifiedCalendar = tizen.calendar.getUnifiedCalendar("EVENT");

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

unifiedCalendar.add(ev);

/* Event has been added. */
/* Checks whether the added event can be retrieved from the calendar. */
/* If the calendar was empty, only the item added through add() should be returned. */
var filter = new tizen.AttributeFilter("summary", "CONTAINS", "HTML5");
unifiedCalendar.find(eventFoundCallback, errorCallback, filter);
getDefaultCalendar
Gets the default calendar, which is used for new items.
Calendar getDefaultCalendar(CalendarType type);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • type: Type of a calendar.

Return value:

    Calendar: The default Calendar object.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var myCalendar;

/* Defines the error callback for all the asynchronous calls. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

function eventFoundCallback(events)
{
  /* Event has been successfully found. */
  /* Changes the summary. */
  events[0].summary = "HTML6 Webinar";
  myCalendar.update(events[0]);
  console.log("First event was updated!");
}

/* Gets the default calendar. */
myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

myCalendar.add(ev);

/* Event has been added. */
/* Checks whether the added event can be retrieved from the calendar. */
/* If the calendar was empty, only the item added through add() should be returned. */
var filter = new tizen.AttributeFilter("summary", "CONTAINS", "HTML5");
myCalendar.find(eventFoundCallback, errorCallback, filter);
addCalendar
Adds a calendar to the calendar database synchronously.
void addCalendar(Calendar calendar);

Since: 2.3

If the calendar is successfully inserted in the database, the Calendar object will have its identifier (id attribute) set when the function returns.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • calendar: Calendar to be added.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if the calendar could not be inserted to an unknown error.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var calendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
        tizen.calendar.addCalendar(calendar);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
removeCalendar
Removes a calendar from the calendar database synchronously.
void removeCalendar(CalendarType type, CalendarId id);

Since: 2.3

Removes the calendar that corresponds to the specified identifier from the database. The function will throw an exception if it failed to remove the specified calendar.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • type: Type of a calendar.
  • id: Identifier (id attribute) of the calendar object to delete.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if there is no calendar with the given identifier.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if the identifier represents default calendar.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if the calendar could not be removed to an unknown error.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var calendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
        tizen.calendar.addCalendar(calendar);
        tizen.calendar.removeCalendar("TASK", calendar.id);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
getCalendar
Gets the calendar with the specified identifier and type.
Calendar getCalendar(CalendarType type, CalendarId id);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • type: Type of a calendar.
  • id: Identifier (id attribute) of the calendar object to get.

Return value:

    Calendar: The matching Calendar object.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if there is no calendar with the given identifier.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var calendarId;  /* calendarId supposed to be initialized. */
try
{
  var calendar = tizen.calendar.getCalendar("EVENT", calendarId);
  console.log("Successfully retrieved event calendar with id: " + calendarId);
}
catch (err)
{
  console.log("Error: " + err.name);
}

2.3. Calendar

The Calendar interface provides methods to manage events or tasks in a calendar. A Calendar object contains a set of events or tasks, depending on the calendar type.
  [Constructor(AccountId accountId, DOMString name, CalendarType type)]
  interface Calendar {
    readonly attribute CalendarId id;
    readonly attribute DOMString name;
    readonly attribute AccountId? accountId;
    CalendarItem get(CalendarItemId id) raises(WebAPIException);
    void add(CalendarItem item) raises(WebAPIException);
    void addBatch(CalendarItem[] items, optional CalendarItemArraySuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);
    void update(CalendarItem item, optional boolean? updateAllInstances) raises(WebAPIException);
    void updateBatch(CalendarItem[] items, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback,
                     optional boolean? updateAllInstances) raises(WebAPIException);
    void remove(CalendarItemId id) raises(WebAPIException);
    void removeBatch(CalendarItemId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
                     raises(WebAPIException);
    void find(CalendarItemArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter,
              optional SortMode? sortMode) raises(WebAPIException);
    long addChangeListener(CalendarChangeCallback successCallback) raises(WebAPIException);
    void removeChangeListener(long watchId) raises(WebAPIException);
  };

Since: 1.0

This interface offers the following methods to manage events in a calendar:

  • Finding items using a key-value filter.
  • Adding items to a specific calendar using add() / addBatch() methods.
  • Updating existing items using update() / updateBatch() methods.
  • Deleting existing items using remove() / removeBatch() methods.
  • Tracking calendar changes using addChangeListener() / removeChangeListener() methods.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var calendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
        /* calendar variable is not available until it is inserted into the database. */
        tizen.calendar.addCalendar(calendar);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);

Constructors

Constructor (AccountId, DOMString, CalendarType)
Calendar(AccountId accountId, DOMString name, CalendarType type);

Attributes

  • readonly CalendarId id
    Calendar identifier.

    Since: 1.0

  • readonly DOMString name
    Readable (descriptive) name for a calendar, such as work or personal.

    Since: 1.0

    Code example:

    /* Gets the default calendar and shows its name. */
    var calendar = tizen.calendar.getDefaultCalendar("EVENT");
    console.log("The calendar name is " + calendar.name);
    
  • readonly AccountId accountId [nullable]
    Account identifier.

    Since: 2.3

Methods

get
Gets the calendar item with the specified identifier.

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • id: Calendar item identifier.

Return value:

    CalendarItem: The matching CalendarItem object.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if there is no calendar item with the given identifier.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var myCalendar;  /* Calendar supposed to be initialized. */
var itemId;      /* Calendar item identifier. */
try
{
  var item = myCalendar.get(itemId);
  console.log("Successfully retrieved item with id: " + itemId);
}
catch (err)
{
  console.log("Error: " + err.name);
}
add
Adds an item to the calendar synchronously.
void add(CalendarItem item);

Since: 1.0

If the item is successfully inserted in the calendar, the CalendarItem will have its identifier (id attribute) set when the method returns.

To update an existing item, call the update() method instead. If you wish to add a copy of an existing CalendarItem object, call CalendarItem.clone() method first and pass the clone to the add() method.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • item: Calendar item to be added.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar("EVENT");

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

calendar.add(ev);
console.log("Event added with uid " + ev.id.uid);
addBatch
Adds an array of items to the calendar asynchronously.
void addBatch(CalendarItem[] items, optional CalendarItemArraySuccessCallback? successCallback,
              optional ErrorCallback? errorCallback);

Since: 1.0

If all the items are successfully added to the calendar, the success callback will be invoked, passing the list of CalendarItem objects that were added, with their identifier set (id attribute).

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if any of the input parameters contain an invalid value, the item has any invalid value or the calendar has some restrictions that cause the attempted insertion of the calendar items to fail (for example, limitations in the size of text attributes).
  • UnknownError - if any other error occurs.

If you wish to update an existing item, call the update() method instead. If you wish to add a copy of an existing CalendarItem object, call CalendarItem.clone() method first and pass the clone to the add() method.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • items: List of calendar items to add.
  • successCallback [optional] [nullable]: Callback method that is invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when the request fails.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

Code example:

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

function addEventsSuccess(events)
{
  console.log("Successfully added " + events.length + " events!");
}

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar("EVENT");

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

calendar.addBatch([ev], addEventsSuccess, errorCallback);
update
Updates an existing item in the calendar synchronously with the one specified in the argument.
void update(CalendarItem item, optional boolean? updateAllInstances);

Since: 1.0

In case of recurring events, the default behavior is to update all their instances (including their detached ones), as well. If you do not want that, the updateAllInstances flag should be set to false.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • item: Item object to update.
  • updateAllInstances [optional] [nullable]: Flag indicating whether all the event instances should be updated as well (default value is true)
    This parameter only applies to calendar events, and does not apply to tasks.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var myCalendar;

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the event success callback. */
function eventSearchSuccessCallback(events)
{
  events[0].description = "New Description";
  /* Updates the first existing event. */
  myCalendar.update(events[0]);
  console.log("The first item description was updated!");
}

/* Gets the default calendar. */
myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Finds all events in a Calendar. */
myCalendar.find(eventSearchSuccessCallback, errorCallback);
updateBatch
Updates an array of existing items in the calendar asynchronously with the specified values in the argument.
void updateBatch(CalendarItem[] items, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback,
                 optional boolean? updateAllInstances);

Since: 1.0

In case of recurring events, the default behavior is to update all their instances (including their detached ones) as well. The updateAllInstances flag should be set to false to change the default behavior.

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if parameters such as the calendar item has any invalid value or the calendar has some restrictions that cause the attempted insertion of the calendar items to fail (for example, limitations in the size of text attributes).
  • UnknownError - if any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Parameters:

  • items: List of calendar item objects to update.
  • successCallback [optional] [nullable]: Callback method that is invoked when the updateEvents() request succeeds.
  • errorCallback [optional] [nullable]: Callback method that is invoked when the updateEvents() request fails.
  • updateAllInstances [optional] [nullable]: Flag indicating whether all the event instances should be updated
    Default value for this flag is true). This parameter applies only to calendar events, and does not apply to tasks.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

Code example:

var myCalendar;

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the success callback. */
function updateEventsSuccess()
{
  console.log("Successfully updated !");
}

/* Defines the event success callback. */
function eventSearchSuccessCallback(events)
{
  events[0].description = "New Description 1";
  events[1].description = "New Description 2";
  /* Updates the first two existing events. */
  myCalendar.updateBatch(events.slice(0, 2), updateEventsSuccess, errorCallback);
}

/* Gets the default calendar. */
myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Finds all events in calendar. */
myCalendar.find(eventSearchSuccessCallback, errorCallback);
remove
Removes an item from the calendar that corresponds to the specified identifier. This method will throw an exception if it fails to remove the specified calendar item.
void remove(CalendarItemId id);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Remark: For (recurring) events: In the case of calendar events, if the recurrence ID (rid attribute) is set to null, this method will remove the event identified by uid, and all of its possible detached instances.

Parameters:

  • id: The identifier (id attribute) of the item object to delete.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the identifier does not match any item in the calendar.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError, if the item could not be removed because of an unknown error.

Code example:

var myCalendar;

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the event success callback. */
function eventSearchSuccessCallback(events)
{
  /* Deletes the first existing event. */
  myCalendar.remove(events[0].id);
  console.log("The first event was removed");
}

/* Gets default calendar. */
myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Finds all events in Calendar. */
myCalendar.find(eventSearchSuccessCallback, errorCallback);
removeBatch
Removes several items from the calendar asynchronously depending on the specified identifiers.
void removeBatch(CalendarItemId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

The ErrorCallback method is launched with these error types:

  • NotFoundError - if an identifier in the ids parameter does not correspond to the id attribute of an item in the calendar.
  • InvalidValuesError - if any of the input parameters contain an invalid value.
  • UnknownError - if any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.write

Remark: For (recurring) events: In the case of calendar events, if the recurrence id, rid, is set to null, this method will remove the event identified by uid, as well as all its possible detached instances.

Parameters:

  • ids: The identifiers (id attribute) of the items to delete.
  • successCallback [optional] [nullable]: Callback method that is invoked when the removeBatch() request succeeds.
  • errorCallback [optional] [nullable]: Callback method that is invoked when the removeBatch() request fails.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

Code example:

var myCalendar;

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the removeBatch callback. */
function removeBatchCallback()
{
  console.log("Requested events were successfully removed");
}

/* Defines the event search success callback. */
function eventSearchSuccessCallback(events)
{
  /* Deletes the first two existing events. */
  myCalendar.removeBatch([events[0].id, events[1].id], removeBatchCallback, errorCallback);
}

/* Gets the default calendar. */
myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Retrieves all the events in Calendar. */
myCalendar.find(eventSearchSuccessCallback, errorCallback);
find
Finds and fetches an array of CalendarItem objects for items stored in the calendar according to the supplied filter if it is valid else it will return all the items stored.
void find(CalendarItemArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter,
          optional SortMode? sortMode);

Since: 1.0

If the filter is passed and contains valid values, only those values in the calendar that match the filter criteria as specified in the AbstractFilter interface will be returned in the successCallback(). If no filter is passed, or the filter contains any invalid value which is null or undefined, then the implementation must return the full list of items in the successCallback(). If no items are available in the calendar (it is empty) or no item matches the filter criteria, the successCallback() will be invoked with an empty array.

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if any of the input parameters contain an invalid value.
  • UnknownError - if any other error occurs.

Filter specific remarks:

  • For event filtering based on start or end dates, items that recur during the given time interval will be found, even if the parent item itself is outside the interval.
  • For event filtering based on the identifier, the identifier type should be CalendarEventID (uid and rid). If no recurrence ID is given, the filter will match both the parent event and all its detached instances.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • successCallback: Callback method that is invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.
  • filter [optional] [nullable]: Supplied data used to filter the results of the find() method.
  • sortMode [optional] [nullable]: Sort order in which the items return.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

Code example:

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the event search success callback. */
function eventSearchSuccessCallback(events)
{
  console.log(events.length + " results found");
}

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Finds all events the calendar that contain in the summary the string Tizen. */
var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");

/* Events returned by the find() query will be sorted by ascending summary. */
var sortingMode = new tizen.SortMode("summary", "ASC");

calendar.find(eventSearchSuccessCallback, errorCallback, filter, sortingMode);
addChangeListener
Adds a listener to receive notifications about calendar changes.
long addChangeListener(CalendarChangeCallback successCallback);

Since: 1.0

When executed, the implementation must immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watcher methods are invoked asynchronously.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • successCallback: Callback methods that is invoked on receiving calendar change notifications.

Return value:

    long: The identifier used to clear the watch subscription.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var calendar;       /* This example assumes calendar is initialized. */

var watcher =
{
  onitemsadded: function(items)
  {
    console.log(items.length + " items were added");
  },
  onitemsupdated: function(items)
  {
    console.log(items.length + " items were updated");
  },
  onitemsremoved: function(ids)
  {
    console.log(ids.length + " items were removed");
  }
};

/* Registers to be notified when the calendar changes. */
watcherId = calendar.addChangeListener(watcher);
removeChangeListener
Unsubscribes from receiving notification for a calendar item change.
void removeChangeListener(long watchId);

Since: 1.0

If the watchId argument is valid and corresponds to a subscription already in place, the watch process must immediately stop and no further callbacks must be invoked. If the watchId argument is not valid or does not correspond to a valid subscription, the method should return without any further action.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • watchId: Subscription identifier.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError if any other error occurs.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var calendar;       /* This example assumes calendar is initialized. */

/* Receives calendar changes. */
var watcher =
{
  onitemsadded: function(items)
  {
    console.log(items.length + " items were added");
  },
  onitemsupdated: function(items)
  {
    console.log(evitemsents.length + " items were updated");
  },
  onitemsremoved: function(ids)
  {
    console.log(ids.length + " items were removed");
  }
};

/* Registers to be notified when the calendar changes. */
watcherId = calendar.addChangeListener(watcher);

/* Cancels the watch operation. */
calendar.removeChangeListener(watcherId);

2.4. CalendarItemInit

The CalendarItemInit dictionary is used for creating calendar items.
  dictionary CalendarItemInit {
    DOMString description;
    DOMString summary;
    boolean isAllDay;
    TZDate startDate;
    TimeDuration duration;
    DOMString location;
    SimpleCoordinates geolocation;
    DOMString organizer;
    CalendarItemVisibility visibility;
    CalendarItemStatus status;
    CalendarItemPriority priority;
    CalendarAlarm[] alarms;
    DOMString[] categories;
    CalendarAttendee[] attendees;
  };

Since: 1.0

These attributes are shared by both calendar events and tasks.

2.5. CalendarTaskInit

The CalendarTaskInit dictionary is used for creating calendar tasks.
  dictionary CalendarTaskInit : CalendarItemInit {
    TZDate dueDate;
    TZDate completedDate;
    short progress;
  };

Since: 1.0

It also provides an interface for specifying task attributes upon task creation (in the CalendarTask constructor).

All the attributes are optional and are undefined by default.

This dictionary inherits from: CalendarItemInit

2.6. CalendarEventInit

The CalendarEventInit dictionary is used for creating calendar events.
  dictionary CalendarEventInit : CalendarItemInit {
    TZDate endDate;
    EventAvailability availability;
    CalendarRecurrenceRule recurrenceRule;
  };

Since: 1.0

Provides an interface for specifying event attributes upon event creation (in the CalendarEvent constructor).

All the attributes are optional and are undefined by default.

This dictionary inherits from: CalendarItemInit

2.7. CalendarItem

The CalendarItem interface is a parent interface that is used to create Calendar events and tasks. These attributes are shared by both events and tasks.
  [NoInterfaceObject] interface CalendarItem {
    readonly attribute CalendarItemId? id;
    readonly attribute CalendarId? calendarId;
    readonly attribute TZDate? lastModificationDate;
    attribute DOMString? description;
    attribute DOMString? summary;
    attribute boolean isAllDay;
    attribute TZDate? startDate;
    attribute TimeDuration? duration;
    attribute DOMString? location;
    attribute SimpleCoordinates? geolocation;
    attribute DOMString? organizer;
    attribute CalendarItemVisibility visibility;
    attribute CalendarItemStatus status;
    attribute CalendarItemPriority priority;
    attribute CalendarAlarm[] alarms;
    attribute DOMString[] categories;
    attribute CalendarAttendee[] attendees;
    DOMString convertToString(CalendarTextFormat format) raises(WebAPIException);
    CalendarItem clone() raises(WebAPIException);
  };

Since: 1.0

Attributes

  • readonly CalendarItemId id [nullable]
    Calendar item identifier.

    Includes a UID and a possible recurrence ID that is needed to identify a particular instance of a recurring event.

    By default, this attribute is set to null.

    Since: 1.0

  • readonly CalendarId calendarId [nullable]
    Identifier of the calendar in which this item is saved.

    By default, this attribute is set to null.

    Since: 2.1

  • readonly TZDate lastModificationDate [nullable]
    The last modified date and time of an item.

    This attribute is automatically populated and cannot be edited by the client. (See RFC 5545 - Section 3.8.7.3).

    Since: 1.0

  • DOMString description [nullable]
    The textual descriptions of an item.

    It is usually used to provide a more complete description of the item and any supporting information than what is provided in the summary attribute. (See RFC 5545 - Section 3.8.1.5).

    The default value is an empty string.

    Since: 1.0

    Code example:

    event.description = "Tizen Codefest";
    
  • DOMString summary [nullable]
    The short summary or subject for an item. (See RFC 5545 - Section 3.8.1.12)

    The default value is an empty string.

    Since: 1.0

    Code example:

    event.summary = "Launching the Tizen reference implementation";
    
  • boolean isAllDay
    Flag to indicate whether an event is an all-day event.

    If set to true, then the time and time zone of the startDate are to be ignored and are not guaranteed to be stored in the database. An all-day event always covers the whole day, regardless of which time zone it was defined in and what the current time zone is. The duration must be n*60*24 minutes for an event lasting n days.

    The default value for this attribute is false.

    Since: 1.0

    Code example:

    event.isAllDay = true;  /* All-day event. */
    
  • TZDate startDate [nullable]
    The start date or time for an item. (see RFC 5545 - Section 3.8.2.4).

    The default value for this attribute is null.

    startDate must be specified in the same time zone as endDate / dueDate if provided.

    This attribute is precise to the second. Milliseconds are ignored.

    Since: 1.0

    Code example:

    /* 2010-04-30 09:00 */
    event.startDate = new tizen.TZDate(2010, 3, 30, 9, 0);
    
  • TimeDuration duration [nullable]
    The duration of the calendar component. (See RFC 5545 - Section 3.8.2.5).

    By default, this attribute is set to null.

    duration and endDate / dueDate are mutually exclusive, hence, only one of them can be non-null.

    This attribute is precise to the second. Milliseconds are ignored.

    Since: 1.0

    Remark: Note that the implementation may not save the duration itself, rather convert it to the corresponding endDate/dueDate attribute and save it. For example, if you set the startDate and the duration attributes and save the item, you may see that the duration is null while endDate/dueDate is non-null after retrieving it because the implementation has calculated the endDate/dueDate based on the duration and the startDate then saved it, not the duration.

    Code example:

    /* 1 hour meeting. */
    event.duration = new tizen.TimeDuration(1, "HOURS");
    
  • DOMString location [nullable]
    The location or the intended venue for the activity defined by the calendar item. (See RFC 5545 - Section 3.8.1.7)

    The default value for this attribute is an empty string.

    Since: 1.0

    Code example:

    event.location = "Huesca";
    
  • SimpleCoordinates geolocation [nullable]
    The global position latitude and longitude of the location where the event is planned to take place. (See RFC 5545 - Section 3.8.1.6).

    Since: 1.0

    Code example:

    event.geolocation = new tizen.SimpleCoordinates(60.175, 24.934);
    
  • DOMString organizer [nullable]
    The name of the person who organized this event. (See RFC 5545 - Section 3.8.4.3).

    By default, this attribute is initialized to an empty string.

    Since: 1.0

    Code example:

    event.organizer = "Mr. Jones";
    
  • CalendarItemVisibility visibility
    The visibility (secrecy) level of the item. (See RFC 5545 - Section 3.8.1.3).

    The default value is PUBLIC.

    Since: 1.0

  • CalendarItemStatus status
    The overall confirmation status for a calendar component. (See RFC 5545 - Section 3.8.1.11).

    The default value for this attribute is NONE.

    Since: 1.0

    Code example:

    event.status = "TENTATIVE";
    
  • CalendarItemPriority priority
    The priority level of an item and may be used to relatively prioritize multiple items during a given period of time. (See RFC 5545 - Section 3.8.1.9).

    The default value for this attribute is NONE priority.

    If the native item database supports another priority schema (such as a range from 1 to 9), the implementation must convert those values to the supported values. For instance, RFC 5545 suggests the following mapping for a range from 1 to 9:

    • 1-4 to HIGH,
    • 5 to MEDIUM,
    • 6-9 to LOW.

    Since: 1.0

    Code example:

    task.priority = "HIGH";
    
  • CalendarAlarm[] alarms
    The array of the alarms (or reminders) associated to an item.

    Since: 1.0

    Code example:

    ev.startDate = new tizen.TZDate(2011, 2, 11, 8, 0, 0);
    /* Gives a sound notification 30 minutes before the item's start time. */
    var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
    ev.alarms = [alarm];
    
  • DOMString[] categories
    The flag that indicates the item categories or subtypes of a calendar component. The categories are useful in searching for a calendar component of a particular type and category. (See RFC 5545 - Section 3.8.1.2).

    Examples of categories are personal, work, vacation, travel, and so on.

    By default, this attribute is set to an empty array.

    Since: 1.0

    Code example:

    event.categories = ["Personal"];
    
  • CalendarAttendee[] attendees
    The array that lists the people attending an event. (See RFC 5545 - Section 3.8.4.3).

    By default, this attribute is set to an empty array.

    Since: 1.0

    Code example:

    var attendee = new tizen.CalendarAttendee("mailto:bob@domain.com", {role: "CHAIR", RSVP: true});
    event.attendees = [attendee];
    

Methods

convertToString
Converts the calendar item to a string format that will be generated and returned synchronously. The export format is set using the format parameter.
DOMString convertToString(CalendarTextFormat format);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • format: Format to use for exporting.

Return value:

    DOMString: The representation of the Calendar item.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Defines the event search success callback. */
function eventSearchSuccessCallback(events)
{
  /* Converts the first event to iCalendar 2.0 format (default). */
  var vevent = events[0].convertToString("ICALENDAR_20");
  console.log("iCalendar 2.0 representation of the event is: " + vevent);
}

function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Gets the default calendar. */
var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");

/* Finds all events in the first calendar that contain in the summary the string Tizen. */
var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
myCalendar.find(eventSearchSuccessCallback, errorCallback, filter);
clone
Clones the CalendarItem object, detached from any calendar.
CalendarItem clone();

Since: 1.0

The CalendarItem object returned by the clone() method will have its identifier set to null and will be detached from any calendar.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Return value:

    CalendarItem: New clone of the CalendarItem object.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

    • with error type UnknownError if any other error occurs.

Code example:

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar();

var html5seminar = new tizen.CalendarEvent(
{
  startDate: new tizen.TZDate(2012, 3, 4),
  duration: new tizen.TimeDuration(3, "DAYS"),
  summary: "HTML5 Seminar"
});

calendar.add(html5seminar);
var tizenseminar = html5seminar.clone();
tizenseminar.summary = "Tizen Seminar";
calendar.add(tizenseminar);

2.8. CalendarTask

This interface implements the CalendarTask object.
  [Constructor(optional CalendarTaskInit? taskInitDict),
   Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
  interface CalendarTask : CalendarItem {
    attribute TZDate? dueDate;
    attribute TZDate? completedDate;
    attribute unsigned short progress;
  };

Since: 1.0

Code example:

var taskCalendar, task;

try
{
  var stringRepresentation = "BEGIN:VCALENDAR\r\n" +
                             "VERSION:2.0\r\n" +
                             "BEGIN:VTODO\r\n" +
                             "DTSTAMP:TZID=CET:20110902T110000Z\r\n" +
                             "DTSTART;TZID=CET:20110906T140000Z\r\n" +
                             "DUE;TZID=CET:20110906T150000Z\r\n" +
                             "SUMMARY:Discuss the schedule\r\n" +
                             "DESCRIPTION:Find the feasible schedule\r\n" +
                             "CATEGORIES:HUMAN RESOURCES\r\n" +
                             "END:VTODO\r\n" +
                             "END:VCALENDAR";
  var format = "ICALENDAR_20";
  var task = new tizen.CalendarTask(stringRepresentation, format);

  taskCalendar = tizen.calendar.getDefaultCalendar("TASK");
  taskCalendar.add(task);
  console.log("Task added with ID " + task.id);
}
catch (err)
{
  console.log("Failed to add VTODO to the calendar, error: " + err.name);
}

Code example:

var taskInit =
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  dueDate: new tizen.TZDate(2011, 5, 30, 10, 0),
  completedDate: new tizen.TZDate(2011, 4, 30, 10, 0),
  progress: "0"
};

var ev = new tizen.CalendarTask(taskInit);

Constructors

Constructor (CalendarTaskInit?)
CalendarTask(optional CalendarTaskInit? taskInitDict);
Constructor (DOMString, CalendarTextFormat)
CalendarTask(DOMString stringRepresentation, CalendarTextFormat format);

Attributes

  • TZDate dueDate [nullable]
    The due date and time for completing a task. (See RFC 5545 - Section 3.8.2.3).

    This dueDate must be in the same time zone as the startDate. The duration and dueDate are mutually exclusive, so only one of them can be non-null.

    This attribute is precise to the second. Milliseconds are ignored.

    The default value is null. If no value is provided, the task does not have a due date.

    Since: 1.0

    Code example:

    task.dueDate = new tizen.TZDate(2011, 2, 11);
    
  • TZDate completedDate [nullable]
    The date and time when an task is completed. (See RFC 5545 - Section 3.8.2.1).

    This attribute is precise to the second. Milliseconds are ignored.

    The default value is null. If no value is provided, the task is not completed yet.

    Since: 1.0

    Code example:

    task.completedDate = new tizen.TZDate(2011, 2, 11);
    
  • unsigned short progress
    The percent of completion of a task.

    The value is a positive integer between 0 and 100. A value of 0 indicates the task has not been started yet. A value of 100 indicates that the task has been completed.

    Integer values in between indicate the percent partially complete. (See RFC 5545 - Section 3.8.1.8).

    The default value is 0, implies that the task has not been started.

    Since: 1.0

    Code example:

    task.progress = 50;  /* 50% done. */
    

2.9. CalendarEvent

This interface implements the calendarEvent object.
  [Constructor(optional CalendarEventInit? eventInitDict),
   Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
  interface CalendarEvent : CalendarItem {
    readonly attribute boolean isDetached;
    attribute TZDate? endDate;
    attribute EventAvailability availability;
    attribute CalendarRecurrenceRule? recurrenceRule;
    void expandRecurrence(TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 1.0

Code example:

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar("EVENT");

try
{
  var stringRepresentation = "BEGIN:VCALENDAR\r\n" +
                             "BEGIN:VEVENT\r\n" +
                             "DTSTAMP:19970901T1300Z\r\n" +
                             "DTSTART:19970903T163000Z\r\n" +
                             "DTEND:19970903T190000Z\r\n" +
                             "SUMMARY:Annual Employee Review\r\n" +
                             "CATEGORIES:BUSINESS,HUMAN RESOURCES\r\n" +
                             "END:VEVENT\r\n" +
                             "END:VCALENDAR";
  var format = "ICALENDAR_20";
  var ev = new tizen.CalendarEvent(stringRepresentation, format);

  calendar.add(ev);
  console.log("Event added with UID " + ev.id.uid);
}
catch (err)
{
  console.log("Failed to add VEVENT to the calendar, error: " + err.name);
}

Code example:

var eventInit =
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
};

var ev = new tizen.CalendarEvent(eventInit);

Constructors

Constructor (CalendarEventInit?)
CalendarEvent(optional CalendarEventInit? eventInitDict);
Constructor (DOMString, CalendarTextFormat)
CalendarEvent(DOMString stringRepresentation, CalendarTextFormat format);

Attributes

  • readonly boolean isDetached
    The flag that indicates whether an instance of a recurring event is detached and if it has been modified and saved to the calendar.

    Since: 1.0

  • TZDate endDate [nullable]
    The end date/time of an event.

    (see RFC 5545 - Section 3.8.2.2).

    This endDate must be in the same time zone as the startDate. Note that duration and endDate are mutually exclusive, only one of them can be non-null.

    This attribute is precise to the second. Milliseconds are ignored.

    The default value for this attribute is null.

    Since: 1.0

    Code example:

    /* 2010-04-30 09:00. */
    event.endDate = new tizen.TZDate(2010, 3, 30, 9, 0);
    
  • EventAvailability availability
    The availability of a person for an event. (See RFC 5545 - Section 3.2.9).

    The default value is BUSY.

    Since: 1.0

  • CalendarRecurrenceRule recurrenceRule [nullable]
    The recurrence rule for the event.

    The generated instances of a recurring event will have the same recurrence rule as their parent. This is useful when editing a particular event instance and choosing to update all instances from it.

    The detached instances (specific instances that have been modified as saved to the calendar) of a recurring event will not have any recurrence rule. No recurrence rule can be set on detached instances either. If one tries to set a recurrence rule on a detached event, a NotSupportedError should be thrown. Detached instances can be distinguished by checking their isDetached attribute. (See RFC 5545, Section 3.3.10.)

    Since: 1.0

    Code example:

    /* Repeats daily for 7 days. */
    var rule = new tizen.CalendarRecurrenceRule("DAILY", {occurrenceCount: 7});
    event.recurrenceRule = rule;
    

Methods

expandRecurrence
Expands a recurring event and returns asynchronously the list of instances occurring in a given time interval (inclusive).
void expandRecurrence(TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback,
                      optional ErrorCallback? errorCallback);

Since: 1.0

This method takes into consideration all the parameters of the event recurrence rule to generate the instances occurring in a given time interval.

The call involves retrieving from the database detached instances of an event to replace their corresponding virtual instances in the returned list. The client can then use CalendarEvent.isDetached attribute to identify detached instances. If the event is not saved to a calendar yet, only virtual instances will be returned.

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if the event in operation is not recurring.
  • UnknownError - if any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/calendar.read

Parameters:

  • startDate: Start date/ time of an event(inclusive).
  • endDate: End date/ time of an event (inclusive).
  • successCallback: Callback method that is invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if the feature is not supported.

Code example:

/* eventId should be set to ID of event obtained with the find function. */
var eventId;
/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* Defines the event expanding success callback. */
function eventExpandingSuccessCallback(events)
{
  console.log(events.length + " event instances were returned");
}

var calendar = tizen.calendar.getDefaultCalendar();
var event = calendar.get(eventId);

if (event.recurrenceRule != null)
{
  /* This is a recurring event. Expands all the instances during August 2011. */
  event.expandRecurrence(new tizen.TZDate(2011, 7, 1), new tizen.TZDate(2011, 7, 31),
      eventExpandingSuccessCallback, errorCallback);
}

2.10. CalendarAttendeeInit

The CalendarAttendeeInit dictionary defines the properties of a CalendarAttendee, to pass to its constructor.
  dictionary CalendarAttendeeInit {
    DOMString name;
    AttendeeRole role;
    AttendeeStatus status;
    boolean RSVP;
    AttendeeType type;
    DOMString? group;
    DOMString delegatorURI;
    DOMString delegateURI;
    ContactRef contactRef;
  };

Since: 1.0

See CalendarAttendee interface for more information about the members.

2.11. CalendarAttendee

The CalendarAttendee interface implements the CalendarAttendee object that contains information about an event attendee.
  [Constructor(DOMString uri, optional CalendarAttendeeInit? attendeeInitDict)]
  interface CalendarAttendee {
    attribute DOMString uri;
    attribute DOMString? name;
    attribute AttendeeRole role;
    attribute AttendeeStatus status;
    attribute boolean RSVP;
    attribute AttendeeType type;
    attribute DOMString? group;
    attribute DOMString? delegatorURI;
    attribute DOMString? delegateURI;
    attribute ContactRef? contactRef;
  };

Since: 1.0

By default, each of the attributes of this interface are undefined.

(For more details, see RFC 5545, Section 3.8.4.1.)

Code example:

var attendee = new tizen.CalendarAttendee("mailto:bob@domain.com", {role: "CHAIR", RSVP: true});
event.attendees = [attendee];

Constructors

Constructor (DOMString, CalendarAttendeeInit?)
CalendarAttendee(DOMString uri, optional CalendarAttendeeInit? attendeeInitDict);

Attributes

  • DOMString uri
    The URI for the attendee.

    This is often an email in the form "mailto:name@domain.com".

    Since: 1.0

  • DOMString name [nullable]
    The name of an attendee.

    Since: 1.0

  • AttendeeRole role
    The role of the attendee.

    (See RFC 5545, Section 3.2.16.)

    The default value is REQ_PARTICIPANT.

    Since: 1.0

  • AttendeeStatus status
    The participant's attendance status. (See RFC 5545, Section 3.2.12.)

    The default value is PENDING.

    Since: 1.0

  • boolean RSVP
    The attendee's participation status reply (RSVP). (See RFC 5545, Section 3.2.17.)

    By default, this attribute is set to FALSE.

    Since: 1.0

  • AttendeeType type
    The type of a participant. (See RFC 5545, Section 3.2.3.)

    The default value is INDIVIDUAL.

    Since: 1.0

  • DOMString group [nullable]
    The participant's group or list membership. (See RFC 5545, Section 3.2.11.)

    Since: 1.0

  • DOMString delegatorURI [nullable]
    The URI of the person who has delegated their participation to this attendee. (See RFC 5545, Section 3.2.4.)

    Since: 1.0

  • DOMString delegateURI [nullable]
    The URI of the attendee to whom the person has delegated his participation. (See RFC 5545, Section 3.2.5.)

    Since: 1.0

  • ContactRef contactRef [nullable]
    The participant's reference in the Contact API.

    If the contact is not resolved, this attribute will be set to null. For more information, see the Contact API.

    Since: 1.0

2.12. CalendarRecurrenceRuleInit

The CalendarRecurrenceRuleInit dictionary defines the properties of a CalendarRecurrenceRule to pass to its constructor.
  dictionary CalendarRecurrenceRuleInit {
    short interval;
    TZDate untilDate;
    long occurrenceCount;
    ByDayValue[] daysOfTheWeek;
    short[] setPositions;
    TZDate[] exceptions;
  };

Since: 1.0

For more information about the members, see CalendarRecurrenceRule interface.

2.13. CalendarRecurrenceRule

The CalendarRecurrenceRule interface implements the CalendarRecurrenceRule object, which contains information about the recurrence of an event. (See RFC 5545, Section 3.3.10.)
  [Constructor(RecurrenceRuleFrequency frequency, optional CalendarRecurrenceRuleInit? ruleInitDict)]
  interface CalendarRecurrenceRule {
    attribute RecurrenceRuleFrequency frequency;
    attribute unsigned short interval;
    attribute TZDate? untilDate;
    attribute long occurrenceCount;
    attribute ByDayValue[] daysOfTheWeek;
    attribute short[] setPositions;
    attribute TZDate[] exceptions;
  };

Since: 1.0

Code example:

/* Repeats daily for 7 days. */
var rule = new tizen.CalendarRecurrenceRule("DAILY", {occurrenceCount: 7});
event.recurrenceRule = rule;

Constructors

Constructor (RecurrenceRuleFrequency, CalendarRecurrenceRuleInit?)
CalendarRecurrenceRule(RecurrenceRuleFrequency frequency, optional CalendarRecurrenceRuleInit? ruleInitDict);

Attributes

  • RecurrenceRuleFrequency frequency
    The frequency of a recurrence rule.

    This property corresponds to FREQ in RFC 5545.

    Since: 1.0

  • unsigned short interval
    The interval for the recurrence rule to repeat over the unit of time indicated by its frequency.

    This attribute is linked to the frequency attribute and for an interval of n, the event will recur every n of recurrence attribute.

    For example, if the interval attribute is set to 2 and frequency attribute is set to WEEKLY, then the event will recur every 2 weeks.

    The default interval value is 1, that is, every day if the CalendarRecurrenceRule frequency attribute is DAILY, every week if frequency is WEEKLY, every month if frequency is MONTHLY or every year if frequency is YEARLY.

    This property corresponds to INTERVAL in RFC 5545.

    Since: 1.0

  • TZDate untilDate [nullable]
    The end date of a recurrence duration of an event using either an end date (untilDate attribute) or a number of occurrences (occurrenceCount attribute).

    By default, this attribute is set to null, meaning that the event recurs infinitely, unless occurrenceCount is set.

    This attribute is precise to the second. Milliseconds are ignored.

    This property corresponds to UNTIL in RFC 5545.

    Since: 1.0

    Remark: In accordance with RFC 5545, UNTIL and COUNT cannot be used together. If both untilDate and occurrenceCount attributes are set, only untilDate will be used.

  • long occurrenceCount
    The number of occurrences of a recurring event.

    The recurrence duration of an event can be defined using either an end date (untilDate attribute) or a number of occurrences (occurrenceCount attribute).

    By default, this attribute is set to -1, meaning that the event recurs infinitely, unless untilDate is set.

    This property corresponds to COUNT in RFC 5545.

    Since: 1.0

    Remark: In accordance with RFC 5545, UNTIL and COUNT cannot be used together. If both untilDate and occurrenceCount attributes are set, only untilDate will be used.

  • ByDayValue[] daysOfTheWeek
    The days of the week associated with the recurrence rule.

    This property value is valid only for recurrence rules with a frequency type of WEEKLY, MONTHLY, and YEARLY.

    This property corresponds to BYDAY in RFC 5545.

    By default, this attribute is set to an empty array.

    Since: 1.0

  • short[] setPositions
    The list of ordinal numbers that filters which recurrences to include in the recurrence rule's frequency.

    For example, a yearly recurrence rule that has a daysOfTheWeek value that specifies Monday through Friday, and a setPositions array containing 2 and -1, occurs only on the second weekday and last weekday of every year.

    Values can be from 1 to 366 or -366 to -1. Negative values indicate counting backwards from the end of the recurrence rule's frequency (week, month, or year).

    This attribute must only be used in conjunction with another BYxxx rule part (such as daysOfTheWeek).

    This property corresponds to BYSETPOS in RFC 5545.

    By default, this attribute is set to an empty array.

    Since: 1.0

  • TZDate[] exceptions
    Array to list date/time exceptions for the recurring event. (See RFC 5545, Section 3.8.5.1.)

    This attribute is precise to the second. Milliseconds are ignored.

    This property corresponds to EXDATE in RFC 5545.

    By default, this attribute is set to an empty array.

    Since: 1.0

2.14. CalendarEventId

The CalendarEventId interface contains a UID and an optional recurrence id attribute to identify calendar events.
  [Constructor(DOMString uid, optional DOMString? rid)]
  interface CalendarEventId {
    attribute DOMString uid;
    attribute DOMString? rid;
  };

Since: 1.0

The recurrence identifier (rid attribute) is used to identify a particular instance of a recurring event. All instances of the same recurring event have the same UID but different recurrence IDs.

Constructors

Constructor (DOMString, DOMString?)
CalendarEventId(DOMString uid, optional DOMString? rid);

Attributes

  • DOMString uid
    The calendar event identifier.

    This value is assigned by the platform when the event is added to the calendar, it is locally unique and persistent for the life time of the event and it cannot be modified by the developers.

    See RFC 5545 (section 3.8.4.7) for more details about this parameter and algorithms to guarantee assignment of unique values. This value is assigned by the platform when the add() method is successfully invoked.

    Since: 1.0

  • DOMString rid [nullable]
    The recurrence ID of a CalendarEvent instance.

    This attribute is used in conjunction with the uid property to identify a specific instance of a recurring event.

    The parent of a recurrence instance has its rid set to null.

    By default, this attribute is set to null. (See RFC 5545 (section 3.8.4.4) for more details about this parameter.)

    Since: 1.0

2.15. CalendarAlarm

The information related to an event alarm or reminder.
  [Constructor(TZDate absoluteDate, AlarmMethod method, optional DOMString? description),
   Constructor(TimeDuration before, AlarmMethod method, optional DOMString? description)]
  interface CalendarAlarm {
    attribute TZDate? absoluteDate;
    attribute TimeDuration? before;
    attribute AlarmMethod method;
    attribute DOMString? description;
  };

Since: 1.0

Code example:

/* Creates a sound alarm at the specified time. */
var alarm1 = new tizen.CalendarAlarm(new tizen.TZDate(2011, 3, 30, 10, 0), "SOUND");

/* Creates a sound alarm before an event starts. */
var alarm2 = new tizen.CalendarAlarm(new tizen.TimeDuration(1, "MINS"), "SOUND");

Constructors

Constructor (TZDate, AlarmMethod, DOMString?)
CalendarAlarm(TZDate absoluteDate, AlarmMethod method, optional DOMString? description);
Constructor (TimeDuration, AlarmMethod, DOMString?)
CalendarAlarm(TimeDuration before, AlarmMethod method, optional DOMString? description);

Attributes

  • TZDate absoluteDate [nullable]
    The absolute date and time when an alarm should be triggered.

    absoluteDate and before are mutually exclusive.

    This attribute is precise to the second. Milliseconds are ignored.

    Since: 1.0

  • TimeDuration before [nullable]
    The duration before an event starts on which the alarm should be triggered.

    The duration should be positive.

    absoluteDate and before are mutually exclusive.

    This attribute is precise to the second. Milliseconds are ignored.

    Since: 1.0

  • AlarmMethod method
    The notification method used by an alarm.

    Since: 1.0

  • DOMString description [nullable]
    The description of an alarm.

    When the method is DISPLAY, the alarm must also include a description attribute, which contains the text to be displayed when the alarm is triggered.

    The default value is an empty string.

    Since: 1.0

2.16. CalendarEventArraySuccessCallback

The CalendarEventArraySuccessCallback interface that implements the success callback used in the asynchronous operation for retrieving a list of calendar events.
  [Callback=FunctionOnly, NoInterfaceObject] interface CalendarEventArraySuccessCallback {
    void onsuccess(CalendarEvent[] events);
  };

Since: 1.0

Methods

onsuccess
Called when the list of calendar events is retrieved successfully.
void onsuccess(CalendarEvent[] events);

Since: 1.0

Parameters:

  • events: Array of CalendarEvent objects.

Code example:

/* eventId should be set to ID of event obtained with the find function. */
var eventId;
/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* CalendarEventArraySuccessCallback instance. */
function calendarEventArraySuccessCB(events)
{
  console.log(events.length + " event instances were returned");
}

var calendar = tizen.calendar.getDefaultCalendar();
var event = calendar.get(eventId);

if (event.recurrenceRule != null)
{
  /* This is a recurring event. Expands all the instances during August 2011. */
  event.expandRecurrence(new tizen.TZDate(2011, 7, 1), new tizen.TZDate(2011, 7, 31),
      calendarEventArraySuccessCB, errorCallback);
}

2.17. CalendarItemArraySuccessCallback

The CalendarItemArraySuccessCallback interface implements the success callback used in the asynchronous operation for retrieving a list of calendar items.
  [Callback=FunctionOnly, NoInterfaceObject] interface CalendarItemArraySuccessCallback {
    void onsuccess(CalendarItem[] items);
  };

Since: 1.0

Methods

onsuccess
Called when the list of calendar items is retrieved successfully.
void onsuccess(CalendarItem[] items);

Since: 1.0

Parameters:

  • items: Array of CalendarItem objects.

Code example:

/* Defines the error callback. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* CalendarItemArraySuccessCallback instance. */
function calendarItemArraySuccessCB(events)
{
  console.log("Successfully added " + events.length + " events!");
}

/* Gets the default calendar. */
var calendar = tizen.calendar.getDefaultCalendar("EVENT");

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

calendar.addBatch([ev], calendarItemArraySuccessCB, errorCallback);

2.18. CalendarArraySuccessCallback

The CalendarArraySuccessCallback interface implements the success callback used in the asynchronous operation to get a list of calendars using the getCalendars() method.
  [Callback=FunctionOnly, NoInterfaceObject] interface CalendarArraySuccessCallback {
    void onsuccess(Calendar[] calendars);
  };

Since: 1.0

Methods

onsuccess
Called when the array of Calendar objects is retrieved successfully.
void onsuccess(Calendar[] calendars);

Since: 1.0

Parameters:

  • calendars: Array of Calendar objects.

Code example:

var calendar;

function eventFoundCallback(events)
{
  /* Event has been successfully found. */
  /* Changes the summary. */
  events[0].summary = "HTML6 Webinar";
  calendar.update(events[0]);
  console.log("First event was updated!");
}

/* Defines the error callback for all the asynchronous calls. */
function errorCallback(response)
{
  console.log("The following error occurred: " + response.name);
}

/* CalendarArraySuccessCallback instance. */
function calendarArraySuccessCB(calendars)
{
  if (calendars.length > 0)
  {
    calendar = calendars[0];
    console.log("The calendar id is " + calendar.id + " and name " + calendar.name);

    var ev = new tizen.CalendarEvent(
    {
      description: "HTML5 Introduction",
      summary: "HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      duration: new tizen.TimeDuration(1, "HOURS"),
      location: "Huesca"
    });
    calendar.add(ev);

    /* Event has been successfully added. */
    /* Checks whether the added event can be retrieved from the calendar. */
    /* If the calendar was empty, only the item added through add() should be returned. */
    var filter = new tizen.AttributeFilter("summary", "CONTAINS", "HTML5");
    calendar.find(eventFoundCallback, errorCallback, filter);
  }
}

/* Gets a list of available calendars. */
tizen.calendar.getCalendars("EVENT", calendarArraySuccessCB, errorCallback);

2.19. CalendarChangeCallback

The CalendarChangeCallback interface specifies a set of methods that will be invoked every time a calendar change occurs (calendar item addition/update/removal).
  [Callback, NoInterfaceObject] interface CalendarChangeCallback {
    void onitemsadded(CalendarItem[] items);
    void onitemsupdated(CalendarItem[] items);
    void onitemsremoved(CalendarItemId[] ids);
  };

Since: 1.0

Methods

onitemsadded
Called when items are added to the calendar.
void onitemsadded(CalendarItem[] items);

Since: 1.0

Parameters:

  • items: List of items that were added.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var calendar;       /* This example assumes calendar is initialized. */

var watcher =
{
  onitemsadded: function(items)
  {
    console.log("New item " + items[0].id + " added");
  },
  onitemsupdated: function(items)
  {
    /* Do something. */
  },
  onitemsremoved: function(ids)
  {
    /* Do something. */
  }
};

/* Registers to be notified when the calendar changes. */
watcherId = calendar.addChangeListener(watcher);

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});
onitemsupdated
Called when items are updated in the calendar.
void onitemsupdated(CalendarItem[] items);

Since: 1.0

Parameters:

  • items: List of items that were updated.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var calendar;       /* This example assumes calendar is initialized. */

var watcher =
{
  onitemsadded: function(items)
  {
    if (calendar.update)
    {
      items[0].location = "New York";
      calendar.update(items[0]);
    }
  },
  onitemsupdated: function(items)
  {
    console.log("Item updated");
  },
  onitemsremoved: function(ids)
  {
    /* Do something. */
  }
};

/* Registers to be notified when the calendar changes. */
watcherId = calendar.addChangeListener(watcher);
var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});
onitemsremoved
Called when item are removed from the calendar.
void onitemsremoved(CalendarItemId[] ids);

Since: 1.0

Parameters:

  • ids: List of identifiers for the items that were removed.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var calendar;       /* This example assumes calendar is initialized. */

var watcher =
{
  onitemsadded: function(items)
  {
    if (calendar.remove)
    {
      calendar.remove(items[0].id);
    }
  },
  onitemsupdated: function(items)
  {
    /* Do something. */
  },
  onitemsremoved: function(ids)
  {
    console.log("Item removed");
  }
};

/* Registers to be notified when the calendar changes. */
watcherId = calendar.addChangeListener(watcher);

var ev = new tizen.CalendarEvent(
{
  description: "HTML5 Introduction",
  summary: "HTML5 Webinar",
  startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
  duration: new tizen.TimeDuration(1, "HOURS"),
  location: "Huesca"
});

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of the application on a device with Account feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/account
  • To guarantee the running of the application on a device with Calendar feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/calendar
  • To guarantee the running of the application on a device with Contact feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/contact
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Calendar {
      typedef DOMString CalendarId;
      typedef DOMString CalendarTaskId;
      typedef (CalendarEventId or CalendarTaskId) CalendarItemId;
      enum CalendarType { "EVENT", "TASK" };
      enum CalendarTextFormat { "ICALENDAR_20", "VCALENDAR_10" };
      enum AlarmMethod { "SOUND", "DISPLAY" };
      enum RecurrenceRuleFrequency { "DAILY", "WEEKLY", "MONTHLY", "YEARLY" };
      enum ByDayValue { "MO", "TU", "WE", "TH", "FR", "SA", "SU" };
      enum EventAvailability { "BUSY", "FREE", "BUSY_UNAVAILABLE", "BUSY_TENTATIVE" };
      enum AttendeeType { "INDIVIDUAL", "GROUP", "RESOURCE", "ROOM", "UNKNOWN" };
      enum AttendeeStatus { "PENDING", "ACCEPTED", "DECLINED", "TENTATIVE", "DELEGATED", "COMPLETED", "IN_PROCESS" };
      enum AttendeeRole { "REQ_PARTICIPANT", "OPT_PARTICIPANT", "NON_PARTICIPANT", "CHAIR" };
      enum CalendarItemPriority { "HIGH", "MEDIUM", "LOW", "NONE" };
      enum CalendarItemVisibility { "PUBLIC", "PRIVATE", "CONFIDENTIAL" };
      enum CalendarItemStatus { "NONE", "TENTATIVE", "CONFIRMED", "CANCELLED", "NEEDS_ACTION", "IN_PROCESS", "COMPLETED" };
      dictionary CalendarItemInit {
        DOMString description;
        DOMString summary;
        boolean isAllDay;
        TZDate startDate;
        TimeDuration duration;
        DOMString location;
        SimpleCoordinates geolocation;
        DOMString organizer;
        CalendarItemVisibility visibility;
        CalendarItemStatus status;
        CalendarItemPriority priority;
        CalendarAlarm[] alarms;
        DOMString[] categories;
        CalendarAttendee[] attendees;
      };
      dictionary CalendarTaskInit : CalendarItemInit {
        TZDate dueDate;
        TZDate completedDate;
        short progress;
      };
      dictionary CalendarEventInit : CalendarItemInit {
        TZDate endDate;
        EventAvailability availability;
        CalendarRecurrenceRule recurrenceRule;
      };
      dictionary CalendarAttendeeInit {
        DOMString name;
        AttendeeRole role;
        AttendeeStatus status;
        boolean RSVP;
        AttendeeType type;
        DOMString? group;
        DOMString delegatorURI;
        DOMString delegateURI;
        ContactRef contactRef;
      };
      dictionary CalendarRecurrenceRuleInit {
        short interval;
        TZDate untilDate;
        long occurrenceCount;
        ByDayValue[] daysOfTheWeek;
        short[] setPositions;
        TZDate[] exceptions;
      };
      Tizen implements CalendarManagerObject;
      [NoInterfaceObject] interface CalendarManagerObject {
        readonly attribute CalendarManager calendar;
      };
      [NoInterfaceObject] interface CalendarManager {
        void getCalendars(CalendarType type, CalendarArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                          raises(WebAPIException);
        Calendar getUnifiedCalendar(CalendarType type) raises(WebAPIException);
        Calendar getDefaultCalendar(CalendarType type) raises(WebAPIException);
        void addCalendar(Calendar calendar) raises(WebAPIException);
        void removeCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
        Calendar getCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
      };
      [Constructor(AccountId accountId, DOMString name, CalendarType type)]
      interface Calendar {
        readonly attribute CalendarId id;
        readonly attribute DOMString name;
        readonly attribute AccountId? accountId;
        CalendarItem get(CalendarItemId id) raises(WebAPIException);
        void add(CalendarItem item) raises(WebAPIException);
        void addBatch(CalendarItem[] items, optional CalendarItemArraySuccessCallback? successCallback,
                      optional ErrorCallback? errorCallback) raises(WebAPIException);
        void update(CalendarItem item, optional boolean? updateAllInstances) raises(WebAPIException);
        void updateBatch(CalendarItem[] items, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback,
                         optional boolean? updateAllInstances) raises(WebAPIException);
        void remove(CalendarItemId id) raises(WebAPIException);
        void removeBatch(CalendarItemId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
                         raises(WebAPIException);
        void find(CalendarItemArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter,
                  optional SortMode? sortMode) raises(WebAPIException);
        long addChangeListener(CalendarChangeCallback successCallback) raises(WebAPIException);
        void removeChangeListener(long watchId) raises(WebAPIException);
      };
      [NoInterfaceObject] interface CalendarItem {
        readonly attribute CalendarItemId? id;
        readonly attribute CalendarId? calendarId;
        readonly attribute TZDate? lastModificationDate;
        attribute DOMString? description;
        attribute DOMString? summary;
        attribute boolean isAllDay;
        attribute TZDate? startDate;
        attribute TimeDuration? duration;
        attribute DOMString? location;
        attribute SimpleCoordinates? geolocation;
        attribute DOMString? organizer;
        attribute CalendarItemVisibility visibility;
        attribute CalendarItemStatus status;
        attribute CalendarItemPriority priority;
        attribute CalendarAlarm[] alarms;
        attribute DOMString[] categories;
        attribute CalendarAttendee[] attendees;
        DOMString convertToString(CalendarTextFormat format) raises(WebAPIException);
        CalendarItem clone() raises(WebAPIException);
      };
      [Constructor(optional CalendarTaskInit? taskInitDict),
       Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
      interface CalendarTask : CalendarItem {
        attribute TZDate? dueDate;
        attribute TZDate? completedDate;
        attribute unsigned short progress;
      };
      [Constructor(optional CalendarEventInit? eventInitDict),
       Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
      interface CalendarEvent : CalendarItem {
        readonly attribute boolean isDetached;
        attribute TZDate? endDate;
        attribute EventAvailability availability;
        attribute CalendarRecurrenceRule? recurrenceRule;
        void expandRecurrence(TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback,
                              optional ErrorCallback? errorCallback) raises(WebAPIException);
      };
      [Constructor(DOMString uri, optional CalendarAttendeeInit? attendeeInitDict)]
      interface CalendarAttendee {
        attribute DOMString uri;
        attribute DOMString? name;
        attribute AttendeeRole role;
        attribute AttendeeStatus status;
        attribute boolean RSVP;
        attribute AttendeeType type;
        attribute DOMString? group;
        attribute DOMString? delegatorURI;
        attribute DOMString? delegateURI;
        attribute ContactRef? contactRef;
      };
      [Constructor(RecurrenceRuleFrequency frequency, optional CalendarRecurrenceRuleInit? ruleInitDict)]
      interface CalendarRecurrenceRule {
        attribute RecurrenceRuleFrequency frequency;
        attribute unsigned short interval;
        attribute TZDate? untilDate;
        attribute long occurrenceCount;
        attribute ByDayValue[] daysOfTheWeek;
        attribute short[] setPositions;
        attribute TZDate[] exceptions;
      };
      [Constructor(DOMString uid, optional DOMString? rid)]
      interface CalendarEventId {
        attribute DOMString uid;
        attribute DOMString? rid;
      };
      [Constructor(TZDate absoluteDate, AlarmMethod method, optional DOMString? description),
       Constructor(TimeDuration before, AlarmMethod method, optional DOMString? description)]
      interface CalendarAlarm {
        attribute TZDate? absoluteDate;
        attribute TimeDuration? before;
        attribute AlarmMethod method;
        attribute DOMString? description;
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface CalendarEventArraySuccessCallback {
        void onsuccess(CalendarEvent[] events);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface CalendarItemArraySuccessCallback {
        void onsuccess(CalendarItem[] items);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface CalendarArraySuccessCallback {
        void onsuccess(Calendar[] calendars);
      };
      [Callback, NoInterfaceObject] interface CalendarChangeCallback {
        void onitemsadded(CalendarItem[] items);
        void onitemsupdated(CalendarItem[] items);
        void onitemsremoved(CalendarItemId[] ids);
      };
    };