Samsung Electronics logo

Samsung Web API: Calendar


Introduction

This 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.

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. To know more about this specification, 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.


Table of Contents


Summary of Interfaces and Methods

Interface Method
CalendarManagerObject
CalendarManager void getCalendars(CalendarType type, CalendarArraySuccessCallback successCallback, ErrorCallback? errorCallback)
Calendar getUnifiedCalendar(CalendarType type)
Calendar getDefaultCalendar(CalendarType type)
Calendar getCalendar(CalendarType type, CalendarId id)
Calendar CalendarItem get(CalendarItemId id)
void add(CalendarItem item)
void addBatch(CalendarItem[] items, CalendarItemArraySuccessCallback? successCallback, ErrorCallback? errorCallback)
void update(CalendarItem item, boolean? updateAllInstances)
void updateBatch(CalendarItem[] items, SuccessCallback? successCallback, ErrorCallback? errorCallback, boolean? updateAllInstances)
void remove(CalendarItemId id)
void removeBatch(CalendarItemId[] ids, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void find(CalendarItemArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode)
long addChangeListener(CalendarChangeCallback successCallback)
void removeChangeListener(long watchId)
CalendarItemInit
CalendarTaskInit
CalendarEventInit
CalendarItem DOMString convertToString(CalendarTextFormat format)
CalendarItem clone()
CalendarTask
CalendarEvent void expandRecurrence(TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback, 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)
void onitemsupdated(CalendarItem[] items)
void onitemsremoved(CalendarItemId[] ids)

1. Type Definitions

1.1. CalendarId

An attribute to identify the calendar.

  typedef DOMString CalendarId;

1.2. CalendarTaskId

An attribute to identify a calendar task.

  typedef DOMString CalendarTaskId;

1.3. CalendarItemId

A calendar item identifier, which can either be a CalendarEventId or a CalendarTaskId.

  typedef (CalendarEventId or CalendarTaskId) CalendarItemId;

1.4. CalendarType

An enumerator that indicates the type of a calendar.

  enum CalendarType { "EVENT", "TASK" };

The following types are supported:

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

1.5. CalendarTextFormat

An enumerator that indicates the type of textual format of a Calendar.

  enum CalendarTextFormat { "ICALENDAR_20", "VCALENDAR_10" };

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

An enumerator that indicates the type of an alarm.

  enum AlarmMethod { "SOUND", "DISPLAY" };

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

An enumerator that indicates the type of frequency for the recurrence of an event.

  enum RecurrenceRuleFrequency { "DAILY", "WEEKLY", "MONTHLY", "YEARLY" };

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

An enumerator that indicates the values for CalendarRecurrenceRule.daysOfWeek.

  enum ByDayValue { "MO", "TU", "WE", "TH", "FR", "SA", "SU" };

"MO" to "SU" correspond to "Monday" to "Sunday".

1.9. EventAvailability

An enumerator that indicates the availability of time for an event.

  enum EventAvailability { "BUSY", "FREE" };

The following values are supported:

  • BUSY - if the specified time slot is not vacant
  • FREE - if the specified time slot is vacant

1.10. AttendeeType

An enumerator that indicates the type of attendee.

  enum AttendeeType { "INDIVIDUAL", "GROUP", "RESOURCE", "ROOM", "UNKNOWN" };

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

An enumerator that indicates the attendance status of a participant.

  enum AttendeeStatus { "PENDING", "ACCEPTED", "DECLINED", "TENTATIVE", "DELEGATED", "COMPLETED", "IN_PROCESS" };

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

An enumerator that indicates the role of an attendee.

  enum AttendeeRole { "REQ_PARTICIPANT", "OPT_PARTICIPANT", "NON_PARTICIPANT", "CHAIR" };

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

An enumerator that indicates the priority of a calendar item.

  enum CalendarItemPriority { "HIGH", "MEDIUM", "LOW" };

The following values are supported:

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

1.14. CalendarItemVisibility

An enumerator that indicates the visibility type of a calendar item.

   enum CalendarItemVisibility { "PUBLIC", "PRIVATE", "CONFIDENTIAL" };

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

An enumerator that indicates the status of a calendar item.

   enum CalendarItemStatus { "TENTATIVE", "CONFIRMED", "CANCELLED", "NEEDS_ACTION", "IN_PROCESS", "COMPLETED" };

For an event, the possible values are:

  • 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:

  • 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

This interface gives access to the Calendar API from the webapis.calendar object.

  [NoInterfaceObject] interface CalendarManagerObject{
    readonly attribute CalendarManager calendar; 
  };
  WebAPIs implements CalendarManagerObject;

2.2. CalendarManager

This 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);
    
    Calendar getCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
  };

METHODS

getCalendars

Gets an array of Calendar objects.

Signature
void getCalendars(CalendarType type, CalendarArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

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 is launched with these error types:

  • InvalidValuesError - if any of the input parameters contain an invalid value.
  • UnknownError - if any other error occurs.
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: CalendarType.
    • Description: The type of calendar.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: CalendarArraySuccessCallback.
    • Description: The method to invoke when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to invoke when an error occurs.
Exceptions
  • WebAPIException:

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

    with error type SecurityError, if this functionality is not allowed.

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

Code example
  var calendar;

  function eventFoundCallback(events) {
    // The 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 webapis.CalendarEvent({description:'HTML5 Introduction',
                                         summary:'HTML5 Webinar', 
                                         startDate: new webapis.TZDate(2011, 3, 30, 10, 0), 
                                         duration: new webapis.TimeDuration(1, "HOURS"),
                                         location:'Huesca'});
      calendar.add(ev);

      // The event has been successfully added
      // Checks if 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 webapis.AttributeFilter('summary', 'CONTAINS', 'HTML5');
      calendar.find(eventFoundCallback, errorCallback, filter);
    }
  }

  // Gets a list of available calendars
  webapis.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.

Signature
Calendar getUnifiedCalendar(CalendarType type);

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

Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: CalendarType.
    • Description: The type of a calendar.
Return value
Calendar The unified Calendar object.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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) {
    // The 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 = webapis.calendar.getUnifiedCalendar("EVENT");

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

  unifiedCalendar.add(ev);
   
  // The event has been added
  // Checks if 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 webapis.AttributeFilter('summary', 'CONTAINS', 'HTML5');
  unifiedCalendar.find(eventFoundCallback, errorCallback, filter);
     

getDefaultCalendar

Gets the default calendar, which is used for new items.

Signature
Calendar getDefaultCalendar(CalendarType type);
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: CalendarType.
    • Description: The type of a calendar.
Return value
Calendar The default Calendar object.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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) {
    // The 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 = webapis.calendar.getDefaultCalendar("EVENT");

  var ev = new webapis.CalendarEvent({description:'HTML5 Introduction', 
                                    summary:'HTML5 Webinar ', 
                                    startDate: new webapis.TZDate(2011, 3, 30, 10, 0), 
                                    duration: new webapis.TimeDuration(1, "HOURS"),
                                    location:'Huesca'});
                  
  myCalendar.add(ev);
   
  // The event has been added
  // Checks if 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 webapis.AttributeFilter('summary', 'CONTAINS', 'HTML5');
  myCalendar.find(eventFoundCallback, errorCallback, filter);
     

getCalendar

Gets the calendar with the specified identifier and type.

Signature
Calendar getCalendar(CalendarType type, CalendarId id);
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: CalendarType.
    • Description: The type of a calendar.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: CalendarId.
    • Description: The calendar identifier.
Return value
Calendar The matching Calendar object.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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

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

2.3. Calendar

This interface that has methods to manage events or tasks in a calendar. A Calendar object contains a set of events or tasks, depending on the calendar type.

  [NoInterfaceObject] interface Calendar {
    
    readonly attribute CalendarId id;

    readonly attribute DOMString name;
                              
    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);
  };

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.

ATTRIBUTES

readonly CalendarId id

An attribute to uniquely identify a calendar.

This attribute is read-only.

readonly DOMString name

An attribute to assign a readable (descriptive) name for a calendar, such as work, personal, etc.

This attribute is read-only.
Code example
  // Gets the default calendar and show its name
  calendar = webapis.calendar.getDefaultCalendar("EVENT");
  console.log('The calendar name is ' + calendar.name);
 

METHODS

get

Gets the calendar item with the specified identifier.

Signature
CalendarItem get(CalendarItemId id);
Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: CalendarItemId.
    • Description: The Calendar item identifier.
Return value
CalendarItem The matching CalendarItem object.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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

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.

Signature
void add(CalendarItem item);

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.

Parameters
  • item
    • Optional: No.
    • Nullable: No.
    • Type: CalendarItem.
    • Description: The calendar item to be added.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

Code example
  // Gets the default calendar
  var calendar = webapis.calendar.getDefaultCalendar("EVENT");
  
  var ev = new webapis.CalendarEvent({description:'HTML5 Introduction', 
                                   summary:'HTML5 Webinar ', 
                                   startDate: new webapis.TZDate(2011, 3, 30, 10, 0), 
                                   duration: new webapis.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.

Signature
void addBatch(CalendarItem[] items, optional CalendarItemArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback);

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() 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.

Parameters
  • items
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The list of calendar items to add.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: CalendarItemArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to invoke when the request fails.
Exceptions
  • WebAPIException:

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

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

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

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 = webapis.calendar.getDefaultCalendar("EVENT");
  
  var ev = new webapis.CalendarEvent({description:'HTML5 Introduction', 
                                   summary:'HTML5 Webinar ', 
                                   startDate: new webapis.TZDate(2011, 3, 30, 10, 0), 
                                   duration: new webapis.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.

Signature
void update(CalendarItem item, optional boolean? updateAllInstances);

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

Parameters
  • item
    • Optional: No.
    • Nullable: No.
    • Type: CalendarItem.
    • Description: The Item object to update.
  • updateAllInstances
    • Optional: Yes.
    • Nullable: Yes.
    • Type: boolean.
    • Description: The flag indicating whether all the event instances should be updated as well or not (default value is true). This parameter only applies to calendar events, and doesn't apply to tasks.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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 = webapis.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.

Signature
void updateBatch(CalendarItem[] items, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional boolean? updateAllInstances);

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() 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.
Parameters
  • items
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The list of calendar item objects to update.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to invoke when the updateEvents() request succeeds.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to invoke when the updateEvents() request fails.
  • updateAllInstances
    • Optional: Yes.
    • Nullable: Yes.
    • Type: boolean.
    • Description: The flag indicating whether all the event instances should be updated or not. Default value for this flag is true). This parameter applies only to calendar events, doesn't apply to tasks.
Exceptions
  • WebAPIException:

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

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

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

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';
    // Update the first two existing events.
    myCalendar.updateBatch(events.slice(0,2), updateEventsSuccess, errorCallback);
  }

  // Gets the default calendar
  myCalendar = webapis.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.

Signature
void remove(CalendarItemId id);

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
    • Optional: No.
    • Nullable: No.
    • Type: CalendarItemId.
    • Description: The identifier (ID attribute) of the item object to delete.
Exceptions
  • WebAPIException:

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

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

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

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

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

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

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 = webapis.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.

Signature
void removeBatch(CalendarItemId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback 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.
Parameters
  • ids
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The identifiers (id attribute) of the items to delete.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to invoke when the removeBatch() request succeeds.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to invoke when the removeBatch() request fails.
Exceptions
  • WebAPIException:

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

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

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

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 default calendar
  myCalendar = webapis.calendar.getDefaultCalendar("EVENT");
    
  // Retrieves all 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.

Signature
void find(CalendarItemArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode);

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 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/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.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: CalendarItemArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: The supplied data used to filter the results of the find() method.
  • sortMode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: The sort order in which the items return.
Exceptions
  • WebAPIException:

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

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

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

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 default calendar
  calendar = webapis.calendar.getDefaultCalendar("EVENT");
  
  // Finds all events the calendar that contain in the summary the string WebAPIs.
  var filter = new webapis.AttributeFilter('summary', 'CONTAINS', 'WebAPIs');

  // The events returned by the find() query will be sorted by ascending summary
  var sortingMode = new webapis.SortMode('summary', 'ASC');
                        
  calendar.find(eventSearchSuccessCallback, errorCallback, filter, sortingMode);
 

addChangeListener

Adds a listener to receive notifications about calendar changes.

Signature
long addChangeListener(CalendarChangeCallback successCallback);

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.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: CalendarChangeCallback.
    • Description: The methods to invoke on receiving calendar change notifications.
Return value
long The identifier used to clear the watch subscription.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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 changes.

Signature
void removeChangeListener(long watchId);

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.

Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Subscription Identifier.
Exceptions
  • WebAPIException:

    with error type UnknownError if any other error occurs.

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

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

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

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

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

A dictionary that 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;
  };

These attributes are shared by both calendar events and tasks.

2.5. CalendarTaskInit

A dictionary that is used for creating calendar tasks.

  dictionary CalendarTaskInit: CalendarItemInit {
    TZDate dueDate;
    TZDate completedDate;
    short progress;
  };

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

A dictionary that is used for creating calendar events.

  dictionary CalendarEventInit: CalendarItemInit {
    TZDate endDate;
    EventAvailability availability;
    CalendarRecurrenceRule recurrenceRule;
  };

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

This 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 setraises(WebAPIException);
    
    attribute DOMString? summary setraises(WebAPIException);
    
    attribute boolean isAllDay setraises(WebAPIException);
    
    attribute TZDate? startDate setraises(WebAPIException);
    
    attribute TimeDuration? duration setraises(WebAPIException);
    
    attribute DOMString? location setraises(WebAPIException);
    
    attribute SimpleCoordinates? geolocation setraises(WebAPIException);
    
    attribute DOMString? organizer setraises(WebAPIException);
    
    attribute CalendarItemVisibility visibility setraises(WebAPIException);
    
    attribute CalendarItemStatus status setraises(WebAPIException);
    
    attribute CalendarItemPriority priority setraises(WebAPIException);
    
    attribute CalendarAlarm[] alarms setraises(WebAPIException);
    
    attribute DOMString[] categories setraises(WebAPIException);
    
    attribute CalendarAttendee[] attendees setraises(WebAPIException);
    
    DOMString convertToString(CalendarTextFormat format) raises(WebAPIException);

    CalendarItem clone() raises(WebAPIException);
  };

ATTRIBUTES

readonly CalendarItemId? id

An attribute to persistently and uniquely identify an item in implementation.

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.

This attribute is read-only.

readonly CalendarId? calendarId

An attribute to identify the calendar in which this item is saved.

By default, this attribute is set to null.

This attribute is read-only.

readonly TZDate? lastModificationDate

An attribute to identify 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).

This attribute is read-only.

DOMString? description

An attribute to store 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.

Code example
  event.description = 'WebAPIs Codefest';
 

DOMString? summary

An attribute to store a short summary or subject for an item. (See RFC 5545 - Section 3.8.1.12)

The default value is an empty string.

Code example
  event.summary = 'Launching the WebAPIs reference implementation';
 

boolean isAllDay

An attribute that behaves like a flag to indicate whether an event is an all-day event or not.

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.

Code example
  event.isAllDay = true; // All-Day event
 

TZDate? startDate

An attribute to store the start date/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.

Code example
  // 2010-04-30 09:00
  event.startDate = new webapis.TZDate(2010, 3, 30, 9, 0);
 

TimeDuration? duration

An attribute to denote 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 have null.

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

Code example
  // 1 hour meeting
  event.duration = new webapis.TimeDuration(1, "HOURS");
 

DOMString? location

An attribute to store 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.

Code example
  event.location = 'Huesca';
 

SimpleCoordinates? geolocation

An attribute to store 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).

Code example
  event.geolocation = new webapis.SimpleCoordinates(60.175, 24.934);
 

DOMString? organizer

An attribute to store 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.

Code example
  event.organizer = 'Mr. Jones';
 

CalendarItemVisibility visibility

An attribute to mark the visibility (secrecy) level of the item. (See RFC 5545 - Section 3.8.1.3).

The default value is PUBLIC.

CalendarItemStatus status

An attribute to store the overall confirmation status for a calendar component. (See RFC 5545 - Section 3.8.1.11).

For an event, the default value is CONFIRMED. For a task, the default value is NEEDS_ACTION.

Code example
  event.status = "TENTATIVE";
 

CalendarItemPriority priority

An attribute to indicate 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 LOW 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.
Code example
  task.priority = "HIGH";
 

CalendarAlarm[] alarms

An attribute array to lists the alarms (or reminders) associated to an item.

Code example
  ev.startDate = new webapis.TZDate(2011, 2, 11, 8, 0, 0);
  // Gives a sound notification 30 minutes before the item's start time
  var alarm = new webapis.CalendarAlarm(new webapis.TimeDuration(30, "MINS"),
                                       "SOUND");
  ev.alarms = [alarm];
 

DOMString[] categories

An attribute to indicate 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, etc.

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

Code example
  event.categories = ['Personal'];
 

CalendarAttendee[] attendees

An attribute 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.

Code example
  var attendee = new webapis.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.

Signature
DOMString convertToString(CalendarTextFormat format);
Parameters
  • format
    • Optional: No.
    • Nullable: No.
    • Type: CalendarTextFormat.
    • Description: The format to use for exporting.
Return value
DOMString The representation of the Calendar item.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

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

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

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

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

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 = webapis.calendar.getDefaultCalendar("EVENT");
    
  // Finds all events in the first calendar that contain in the summary the string WebAPIs.
  var filter = new webapis.AttributeFilter('summary', 'CONTAINS', 'WebAPIs');
  myCalendar.find(eventSearchSuccessCallback, errorCallback, filter);
 

clone

Clones the CalendarItem object, detached from any calendar.

Signature
CalendarItem clone();

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

Return value
CalendarItem The new clone of the CalendarItem object.
Exceptions
  • WebAPIException:

    with error type UnknownError if any other error occurs.

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

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

Code example
  // Gets default calendar.
  var calendar = webapis.calendar.getDefaultCalendar();

  var html5seminar = new webapis.CalendarEvent({startDate: new webapis.TZDate(2012, 3, 4),
                                              duration: new webapis.TimeDuration(3, "DAYS"),
                                              summary: "HTML5 Seminar"});
                                     
  calendar.add(html5seminar);
  var seminar = html5seminar.clone();
  seminar.summary = "WebAPIs Seminar";
  calendar.add(seminar);
 

2.8. CalendarTask

An interface that implements the CalendarTask object.

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

ATTRIBUTES

TZDate? dueDate

An attribute to store 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 have the value null at any given time.

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

By default, this attribute is set to null. If no value is provided, the task doesn't have a due date.

Code example
  task.dueDate = new webapis.TZDate(2011, 2, 11);
 

TZDate? completedDate

An attribute to record 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.

By default, this attribute is set to null. If no value is provided, the task is not completed yet.

Code example
  task.completedDate = new webapis.TZDate(2011, 2, 11);
 

unsigned short progress

An attribute to denote 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.

Code example
  task.progress = 50; // 50% done
 

2.9. CalendarEvent

An interface that implements the calendarEvent object.

  [Constructor(optional CalendarEventInit? eventInitDict),
   Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
  interface CalendarEvent : CalendarItem {
    readonly attribute boolean isDetached;
    
    attribute TZDate? endDate setraises(WebAPIException);
    
    attribute EventAvailability availability setraises(WebAPIException);
    
    attribute CalendarRecurrenceRule? recurrenceRule setraises(WebAPIException);
    
    void expandRecurrence(TZDate startDate,
                          TZDate endDate,
                          CalendarEventArraySuccessCallback successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
Code example
  // Gets the default calendar
  var calendar = webapis.calendar.getDefaultCalendar("EVENT");

  try {
    var ev = new webapis.CalendarEvent("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", "ICALENDAR_20");
                   
    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);
  }
 

ATTRIBUTES

readonly boolean isDetached

An attribute that behaves like a flag to indicates if an instance of a recurring event is detached and if it has been modified and saved to the calendar.

This attribute is read-only.

TZDate? endDate

An attribute to store 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.

Code example
  // 2010-04-30 09:00
  event.endDate = new webapis.TZDate(2010, 3, 30, 9, 0);
 

EventAvailability availability

An attribute to indicate the availability of a person for an event. (See RFC 5545 - Section 3.2.9).

The default value is BUSY.

CalendarRecurrenceRule? recurrenceRule

An attribute to denote 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.)

Code example
  // Repeats daily for 7 days
  var rule = new webapis.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).

Signature
void expandRecurrence(TZDate startDate, TZDate endDate, CalendarEventArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

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 is launched with these error types:

  • InvalidValuesError - if the event given in argument is not a recurring event.
  • UnknownError - if any other error occurs.
Parameters
  • startDate
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: The start date/ time of an event(inclusive).
  • endDate
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: The end date/ time of an event (inclusive).
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: CalendarEventArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
Exceptions
  • WebAPIException:

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

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

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

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 = webapis.calendar.getDefaultCalendar();
  var event = calendar.get(eventId);

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

2.10. CalendarAttendeeInit

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;
  };

See CalendarAttendee interface for more information about the members.

2.11. CalendarAttendee

This 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;
  };

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 webapis.CalendarAttendee('mailto:bob@domain.com',
                                           {role: "CHAIR", RSVP: true});
  event.attendees = [attendee];
 

ATTRIBUTES

DOMString uri

An attribute to store the URI for the attendee.

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

DOMString? name

An attribute to store the name of an attendee.

AttendeeRole role

An attribute to denote the role of the attendee.

(See RFC 5545, Section 3.2.16.)

The default value is REQ_PARTICIPANT.

AttendeeStatus status

An attribute to store the participant's attendance status. (See RFC 5545, Section 3.2.12.)

The default value is PENDING.

boolean RSVP

An attribute to store the attendee's participation status reply (RSVP). (See RFC 5545, Section 3.2.17.)

By default, this attribute is set to FALSE.

AttendeeType type

An attribute to indicate the type of a participant. (See RFC 5545, Section 3.2.3.)

The default value is INDIVIDUAL.

DOMString? group

An attribute to store the participant's group or list membership. (See RFC 5545, Section 3.2.11.)

DOMString? delegatorURI

An attribute to store the URI of the person who has delegated their participation to this attendee. (See RFC 5545, Section 3.2.4.)

DOMString? delegateURI

An attribute to stores the URI of the attendee to whom the person has delegated his participation. (See RFC 5545, Section 3.2.5.)

ContactRef? contactRef

An attribute to store 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.

2.12. CalendarRecurrenceRuleInit

The properties of a CalendarRecurrenceRule to pass to its constructor.

  dictionary CalendarRecurrenceRuleInit {
    short interval;
    TZDate untilDate;
    long occurrenceCount;
    ByDayValue[] daysOfTheWeek;
    short[] setPositions;
    TZDate[] exceptions;
  };

For more information about the members, see CalendarRecurrenceRule interface.

2.13. CalendarRecurrenceRule

This 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;
  };
Code example
  // Repeats daily for 7 days
  var rule = new webapis.CalendarRecurrenceRule("DAILY", {occurrenceCount:7});
  event.recurrenceRule = rule;
 

ATTRIBUTES

RecurrenceRuleFrequency frequency

An attribute to store the frequency of a recurrence rule.

This property corresponds to FREQ in RFC 5545.

unsigned short interval

An attribute to specify how often the recurrence rule repeats 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.

TZDate? untilDate

An attribute to indicate 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.

long occurrenceCount

An attribute to indicate 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.

ByDayValue[] daysOfTheWeek

An attribute to store 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.

short[] setPositions

An attribute to store a 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.

TZDate[] exceptions

An attribute 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.

2.14. CalendarEventId

This 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;
  };

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.

ATTRIBUTES

DOMString uid

An attribute to persistently, and uniquely identify a calendar event.

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.

DOMString? rid

An attribute to store 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.)

2.15. CalendarAlarm

An interface that contains 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 setraises(WebAPIException);
    
    attribute TimeDuration? before setraises(WebAPIException);
  
    attribute AlarmMethod method setraises(WebAPIException);
    
    attribute DOMString? description;
  };
Code example
  // Creates a sound alarm 30 minutes before the event's start time
  var alarm = new webapis.CalendarAlarm(new webapis.TimeDuration(30, "MINS"), "SOUND");
 

ATTRIBUTES

TZDate? absoluteDate

An attribute to record 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.

TimeDuration? before

An attribute to store 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.

AlarmMethod method

An attribute to denote the notification method used by an alarm.

DOMString? description

An attribute to store the description of an alarm.

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

2.16. CalendarEventArraySuccessCallback

An 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);
  };

METHODS

onsuccess

Called when the list of calendar events is retrieved successfully.

Signature
void onsuccess(CalendarEvent[] events);
Parameters
  • events
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The array of CalendarEvent objects.

2.17. CalendarItemArraySuccessCallback

This 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);
  };

METHODS

onsuccess

Called when the list of calendar items is retrieved successfully.

Signature
void onsuccess(CalendarItem[] items);
Parameters
  • items
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The array of CalendarItem objects.

2.18. CalendarArraySuccessCallback

This 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);
  };

METHODS

onsuccess

Called when the array of Calendar objects is retrieved successfully.

Signature
void onsuccess(Calendar[] calendars);
Parameters
  • calendars
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The array of Calendar objects.

2.19. CalendarChangeCallback

This 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);
  };

METHODS

onitemsadded

Called when items are added to the calendar.

Signature
void onitemsadded(CalendarItem[] items);
Parameters
  • items
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The list of items that were added.

onitemsupdated

Called when items are updated in the calendar.

Signature
void onitemsupdated(CalendarItem[] items);
Parameters
  • items
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The list of items that were updated.

onitemsremoved

Called when item are removed from the calendar.

Signature
void onitemsremoved(CalendarItemId[] ids);
Parameters
  • ids
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The list of identifiers for the items that were removed.

3. 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" };
  
  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" };
  
   enum CalendarItemVisibility { "PUBLIC", "PRIVATE", "CONFIDENTIAL" };
   
   enum CalendarItemStatus { "TENTATIVE", "CONFIRMED", "CANCELLED", "NEEDS_ACTION", "IN_PROCESS", "COMPLETED" };
  
  [NoInterfaceObject] interface CalendarManagerObject{
    readonly attribute CalendarManager calendar; 
  };
  WebAPIs implements CalendarManagerObject;    

  [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);
    
    Calendar getCalendar(CalendarType type, CalendarId id) raises(WebAPIException);
  };

  [NoInterfaceObject] interface Calendar {
    
    readonly attribute CalendarId id;

    readonly attribute DOMString name;
                              
    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);
  };
  
  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;
  };
  
  [NoInterfaceObject] interface CalendarItem {
    readonly attribute CalendarItemId? id;

    readonly attribute CalendarId? calendarId;

    readonly attribute TZDate? lastModificationDate;
    
    attribute DOMString? description setraises(WebAPIException);
    
    attribute DOMString? summary setraises(WebAPIException);
    
    attribute boolean isAllDay setraises(WebAPIException);
    
    attribute TZDate? startDate setraises(WebAPIException);
    
    attribute TimeDuration? duration setraises(WebAPIException);
    
    attribute DOMString? location setraises(WebAPIException);
    
    attribute SimpleCoordinates? geolocation setraises(WebAPIException);
    
    attribute DOMString? organizer setraises(WebAPIException);
    
    attribute CalendarItemVisibility visibility setraises(WebAPIException);
    
    attribute CalendarItemStatus status setraises(WebAPIException);
    
    attribute CalendarItemPriority priority setraises(WebAPIException);
    
    attribute CalendarAlarm[] alarms setraises(WebAPIException);
    
    attribute DOMString[] categories setraises(WebAPIException);
    
    attribute CalendarAttendee[] attendees setraises(WebAPIException);
    
    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 setraises(WebAPIException);
    
    attribute TZDate? completedDate setraises(WebAPIException);
    
    attribute unsigned short progress setraises(WebAPIException);
  };

  [Constructor(optional CalendarEventInit? eventInitDict),
   Constructor(DOMString stringRepresentation, CalendarTextFormat format)]
  interface CalendarEvent : CalendarItem {
    readonly attribute boolean isDetached;
    
    attribute TZDate? endDate setraises(WebAPIException);
    
    attribute EventAvailability availability setraises(WebAPIException);
    
    attribute CalendarRecurrenceRule? recurrenceRule setraises(WebAPIException);
    
    void expandRecurrence(TZDate startDate,
                          TZDate endDate,
                          CalendarEventArraySuccessCallback successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
  
  dictionary CalendarAttendeeInit {
    DOMString name;
    AttendeeRole role;
    AttendeeStatus status;
    boolean RSVP;
    AttendeeType type;
    DOMString? group;
    DOMString delegatorURI;
    DOMString delegateURI;
    ContactRef contactRef;
  };

  [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;
  };
  
  dictionary CalendarRecurrenceRuleInit {
    short interval;
    TZDate untilDate;
    long occurrenceCount;
    ByDayValue[] daysOfTheWeek;
    short[] setPositions;
    TZDate[] exceptions;
  };
  
  [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 setraises(WebAPIException);
    
    attribute TimeDuration? before setraises(WebAPIException);
  
    attribute AlarmMethod method setraises(WebAPIException);
    
    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);
  };
};