Bondi logo

The BONDI calendar Module - Version 1.1

9 February 2010

Authors

© 2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

This module provides access to device calendars.

Table of Contents

Summary of Methods

InterfaceMethod
EventsArraySuccessCallbackvoid onSuccess(EventsArray obj)
CalendarArraySuccessCallbackvoid onSuccess(CalendarArray obj)
CalendarManagerPendingOperation getCalendars(CalendarArraySuccessCallback successCallback, ErrorCallback errorCallback)
CalendarEvent createEvent(EventProperties options)
PendingOperation addEvent(SuccessCallback successCallback, ErrorCallback errorCallback, Event event)
PendingOperation updateEvent(SuccessCallback successCallback, ErrorCallback errorCallback, Event event)
PendingOperation deleteEvent(SuccessCallback successCallback, ErrorCallback errorCallback, Event event)
PendingOperation findEvents(EventsArraySuccessCallback successCallback, ErrorCallback errorCallback, EventFilter filter)
Event
EventProperties
EventFilter
CalendarManagerObject

1. Introduction

The BONDI Calendar API provides access to the calendars and events stored in the device. A calendar is a collection of events. Common Events are grouped in calendars, i.e. Work Calendar, Personal Calendar. This API provides functionality to read, create, delete and update events in specific calendars. Calendar can be obtained using the getCalendars method which returns an array of calendar objects. An event is an appointment in the calendar with a start time, end time, duration, location and recurrence indicator.

The recurrence indicator of an event will be set using one of the constants defined in the API.
- NO_RECURRENCE
- DAILY_RECURRENCE
- WEEKLY_RECURRENCE
- MONTHLY_RECURRENCE
- YEARLY_RECURRENCE

Finding events using a filter is also supported with the method findEvents.

1.1. Feature set

This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.

http://bondi.omtp.org/api/1.1/pim.calendar

All the Calendar features

Includes API features:

  • http://bondi.omtp.org/api/1.1/pim.calendar.read
  • http://bondi.omtp.org/api/1.1/pim.calendar.write

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When any of the features

is successfully requested, the interface CalendarManager is instantiated, and the resulting object appears in the global namespace as .calendar.

http://bondi.omtp.org/api/1.1/pim.calendar.read

Calls to read calendars

Device capabilities:

  • pim.calendar.read
http://bondi.omtp.org/api/1.1/pim.calendar.write

Call to create, update or delete events from calendar.

Device capabilities:

  • pim.calendar.write

1.3. Device capabilities

pim.calendar.write

Writes events into the terminal storage

pim.calendar.read

Read events from the terminal storage

2. Type Definitions

2.1. EventsArray

Array of Events. 

        typedef sequence<Event> EventsArray;

2.2. CalendarArray

Array of Calendars. 

        typedef sequence<Calendar> CalendarArray;

3. Interfaces

3.1. EventsArraySuccessCallback

Success callback for retrieving a list of calendar events. 

        [Callback=FunctionOnly, NoInterfaceObject] interface EventsArraySuccessCallback {
                void onSuccess(in EventsArray obj);
        };

Success callback that is used in the asynchronous operation to get a list of Events.

Methods

onSuccess

Method invoked when the list of calendar events is retrieved successfully

Signature
void onSuccess(in EventsArray obj);
Parameters
  • obj: List of calendar events

3.2. CalendarArraySuccessCallback

Success callback for retrieving a list of calendars. 

        [Callback=FunctionOnly, NoInterfaceObject] interface CalendarArraySuccessCallback {
                void onSuccess(in CalendarArray obj);
        };

Success callback that is used in the asynchronous operation to get a list of Calendars.

Methods

onSuccess

Method invoked when the list of calendars is retrieved successfully

Signature
void onSuccess(in CalendarArray obj);
Parameters
  • obj: List of calendars

3.3. CalendarManager

Master event management interface 

        [NoInterfaceObject] interface CalendarManager {

                PendingOperation getCalendars(in CalendarArraySuccessCallback successCallback,
                                in ErrorCallback errorCallback);

        };

The Calendar Manager interface offers methods to retrieve calendars. This API can manage different calendars stored in the device. A calendar is a group of events. The getCalendars methods will retrieve all the calendars stored in the device

Methods

getCalendars

Gets the available calendars on the device. All calendars created on the device are available.

Signature
PendingOperation getCalendars(in CalendarArraySuccessCallback successCallback, in ErrorCallback errorCallback);

This is an asynchronous method.

If no Calendar is available the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.calendar.read
Code example
        // Define the success callback.
        function calendarsSuccessCallback(calendars) {
                // do something with resulting calendars
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);

3.4. Calendar

The Calendar interface offers methods to manage events in the calendar. 

        [NoInterfaceObject] interface Calendar {

                const unsigned short SIM_CALENDAR = 0;

                const unsigned short DEVICE_CALENDAR = 1;

                readonly attribute unsigned short type;

                readonly attribute DOMString name;

                Event createEvent([Optional] in EventProperties options)
                        raises(DeviceAPIError);

                PendingOperation addEvent(in SuccessCallback successCallback,
                                                in ErrorCallback errorCallback,
                                                in Event event);

                PendingOperation updateEvent(in SuccessCallback successCallback,
                                                in ErrorCallback errorCallback,
                                                in Event event);

                PendingOperation deleteEvent(in SuccessCallback successCallback,
                                                in ErrorCallback errorCallback,
                                                in Event event);

                PendingOperation findEvents(in EventsArraySuccessCallback successCallback,
                                            in ErrorCallback errorCallback,
                                            [Optional]in EventFilter filter);
        };

This interface provide methods to: Find events using a key-value filter. Add an event to a specific calendar using addEvent method. Update an existing event using updateEvent method. Delete an existing event using deleteEvent method. Clear all events of a specific calendar with clearEvents method.

Constants

unsigned short SIM_CALENDAR

Constant used to identify SIM Calendar.

unsigned short DEVICE_CALENDAR

Constant used to identify Device Calendar.

Attributes

readonly unsigned short type

Calendar Type Read only.

It MUST be one of the below constants: SIM_CALENDAR = 0 DEVICE_CALENDAR = 1

Code example
        // Define the success callback.
        function calendarsSuccessCallback(calendars) {
          alert("The calendar type is " + calendars[0].type);   
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);
readonly DOMString name

Calendar Readable Name Read only.

Code example
        // Define the success callback.
        function calendarsSuccessCallback(calendars) {
          alert("The calendar name is " + calendars[0].name);   
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);

Methods

createEvent

Creates an event object.

Signature
Event createEvent(in EventProperties options);

Takes an EventOptions object as input data an initializes the event attributes based in its content

Parameters
  • options: Event data
Return value
The created Event object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the options are wrong

Code example
        // Define the calendar book success callback.
        function calendarsSuccessCallback(calendars) {

                // Create an event in the first calendar.
                var event = calendars[0].createEvent({description:'BONDI Codefest', summary:'foo', startTime: new Date(2009, 3, 30, 10, 0), endTime: new Date(2009, 3, 30, 11, 0), location:'Huesca' });

        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);
addEvent

Adds an event to the calendar.

Signature
PendingOperation addEvent(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Event event);

This is an asynchronous method.

If the event is successfully added, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • event: An Event object for the event to be added.
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.calendar.write
Code example
        // Define the calendar success callback.
        function calendarsSuccessCallback(calendars) {

                // Create an event in the first calendar.
                var event = calendars[0].createEvent({description:'BONDI Codefest', summary:'foo', startTime: new Date(2009, 3, 30, 10, 0), endTime: new Date(2009, 3, 30, 11, 0), location:'Huesca' });

                // Add event to the calendar.
                calendars[0].addEvent(calendarSuccessCallback, errorCallback, event);
        }

        // Define the addEvent success callback.
        function calendarSuccessCallback(response) {
                alert("Added");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);
updateEvent

Updates an existing event in the calendar.

Signature
PendingOperation updateEvent(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Event event);

This is an asynchronous method.

If the event is successfully updated, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • event: An Event object for the event to be updated.
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.calendar.write
Code example
        var myCalendars;

        // Define the calendar success callback.
        function calendarsSuccessCallback(calendars) {
                // Set global calendars
                myCalendars = calendars;
                // Find all events in the first calendar.
                myCalendars[0].findEvents(calendarSearchSuccessCallback, errorCallback, null);

        }

        // Define the findEvent success callback.
        function calendarSearchSuccessCallback(events) {
                events[0].location = "New location";

                // Update first event in first calendar.
                myCalendars[0].updateEvent(calendarSuccessCallback, errorCallback, events[0]);
        }

        // Define the updateEvent success callback.
        function calendarSuccessCallback(response) {
                alert("Updated");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);
deleteEvent

Deletes the given event from the calendar.

Signature
PendingOperation deleteEvent(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Event event);

This is an asynchronous method.

If the event is successfully deleted, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • event: An Event object for the event to be updated.
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.calendar.write
Code example
        var myCalendars;

        // Define the calendar success callback.
        function calendarsSuccessCallback(calendars) {
                // Set global calendars
                myCalendars = calendars;
                // Find all events in the first calendar.
                myCalendars[0].findEvents(calendarSearchSuccessCallback, errorCallback, null);

        }

        // Define the findEvents success callback.
        function calendarSearchSuccessCallback(events) {
                // Delete first event in first calendar.
                myCalendars[0].deleteEvent(calendarSuccessCallback, errorCallback, events[0]);
        }

        // Define the deleteEvent success callback.
        function calendarSuccessCallback(response) {
                alert("Deleted");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);
findEvents

Gets an array of Event objects events stored within the calendar and matching the selected filter.

Signature
PendingOperation findEvents(in EventsArraySuccessCallback successCallback, in ErrorCallback errorCallback, in EventFilter filter);

This is an asynchronous method.

The filtering is implemented according to the design patterns (chapter 2.4). If no filter is passed all the events will be returned.

If the method is successfully executed, the SuccessCallback is invoked.

If no event is available in the calendar the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully, use response object to retrieve the array of Event objects.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
  • filter: Event options to be used when filtering
Return value
PendingOperation in order to cancel the async call
API features
http://bondi.omtp.org/api/1.1/pim.calendar.read
Code example
        // Define the calendar success callback.
        function calendarsSuccessCallback(calendars) {
                // Find all events with a location of 'Huesca'.
                calendars[0].findEvents(calendarSearchSuccessCallback, errorCallback, {location:"Huesca"});
        }

        // Define the findEvents success callback.
        function calendarSearchSuccessCallback(events) {
                // Do something with the resulting events found.
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error occured: " +  response.code);
        }

        // Get a list of available calendars.
        bondi.pim.calendar.getCalendars(calendarsSuccessCallback,errorCallback);

3.5. Event

Event object Abstraction of a device event. This interface extends EventProperties to manage each event property. It also has methods to get a specific property and to get the available properties to use in the addEvent and updateEvent methods. 

        [NoInterfaceObject] interface Event : EventProperties {
                readonly attribute DOMString id;

        };

Attributes

readonly DOMString id

Unique identifier assigned to the event in the platform.

Read only.

Code example
        var event = calendar.createEvent();
        alert(event.id);

3.6. EventProperties

Interface used for event creation. 

        [NoInterfaceObject] interface EventProperties {

                const unsigned short NO_RECURRENCE  = 0;

                const unsigned short DAILY_RECURRENCE = 1;

                const unsigned short WEEKLY_RECURRENCE = 2;

                const unsigned short MONTHLY_RECURRENCE = 3;

                const unsigned short YEARLY_RECURRENCE = 4;

                const unsigned short TENTATIVE_STATUS = 0;

                const unsigned short CONFIRMED_STATUS = 1;
                
                const unsigned short CANCELLED_STATUS = 2;

                const unsigned short NO_ALARM = 0;
                
                const unsigned short SILENT_ALARM = 1;
                
                const unsigned short SOUND_ALARM = 2;
        
                attribute DOMString description;

                attribute DOMString summary;

                attribute Date startTime;

                attribute Date endTime;

                attribute DOMString location;

                attribute unsigned short recurrence;

                attribute DOMString status;
      
                attribute Date alarmDate;
   
                attribute unsigned long alarmType;
        
        };

This interface is intended to be used for input parameters for event creation (createEvent).

It includes methods to get a specific property and to set the available properties to use in the findEvents filter, addEvent and updateEvent methods.

All the attributes are optional and by default are undefined.

Constants

unsigned short NO_RECURRENCE

The calendar entry occurs once

unsigned short DAILY_RECURRENCE

The calendar entry occurs every day

unsigned short WEEKLY_RECURRENCE

The calendar entry occurs every week

unsigned short MONTHLY_RECURRENCE

The calendar entry occurs every month

unsigned short YEARLY_RECURRENCE

The calendar entry occurs every year

unsigned short TENTATIVE_STATUS

The calendar entry is tentative

unsigned short CONFIRMED_STATUS

The calendar entry is confirmed

unsigned short CANCELLED_STATUS

The calendar entry is cancelled

unsigned short NO_ALARM

The calendar entry has no alarm

unsigned short SILENT_ALARM

The calendar entry has a silent alarm

unsigned short SOUND_ALARM

The calendar entry has an alarm with sound

Attributes

DOMString description

Description of the event.

Code example
        var event = calendar.createEvent();
        event.description = "BONDI Codefest";
DOMString summary

Summary of the event.

Code example
        var event = calendar.createEvent();
        event.summary = "Launching the BONDI reference implementation";
Date startTime

Starttime of the event.

Code example
        var event = calendar.createEvent();
        event.startTime = new Date(2009, 3, 30, 9, 0);
Date endTime

Sets the end time of the event.

Code example
        var event = calendar.createEvent();
        event.endTime = new Date(2009, 3, 30, 11, 0);
DOMString location

Location of the event.

Code example
        var event = calendar.createEvent();
        event.location = "Huesca";
unsigned short recurrence

Recurrence of the event.

Code example
        var event = calendar.createEvent();
        event.recurrence = bondi.pim.calendar.NO_RECURRENCE;
DOMString status

Status of the event.

Code example
        var event = calendar.createEvent();
        event.status = bondi.pim.calendar.TENTATIVE_STATUS;
Date alarmDate

Event alarm date

Code example
        var event = calendar.createEvent();
        event.alarmDate = new Date(2009, 3, 30, 11, 0);
unsigned long alarmType

Event Alarm Type

Code example
        var event = calendar.createEvent();
        event.alarmType = bondi.pim.calendar.NO_ALARM;

3.7. EventFilter

Interface used to create Filter objects following the Event structure. 

   [NoInterfaceObject] interface EventFilter : GenericFilter {
   };

3.8. CalendarManagerObject

Specifies what is instantiated at feature request 

        interface CalendarManagerObject {
                readonly attribute CalendarManager calendar; 
        };