Bondi logo

The Bondi calendar Module - Version 1.1

12 May 2009

Authors

© 2009 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)
CalendarManagerCalendarArray getCalendars()
CalendarEvent createEvent(EventOptions options)
void addEvent(Event event)
void updateEvent(Event event)
void deleteEvent(Event event)
PendingOperation clearEvents(SuccessCallback successCallback, ErrorCallback errorCallback)
PendingOperation findEvents(SuccessCallback successCallback, ErrorCallback errorCallback, EventFilter filter)
EventObject getProperty(DOMString propertyName)
StringArray getSupportedPropertyKeys()
void setProperty(DOMString propertyName, Object propertyValue)
EventOptions
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. The supported properties are returned by the event class method getSupportedPropertyKeys. These supported keys are valid for the createEvent and/or updateEvent method.

Code example
        // Get the array of all calendars on the device.
        var calendars = bondi.pim.calendar.getCalendars();

        // Use the first calendar.
        var calendar = calendars[0];

        // Define the success callback for findEvents.
        function successGetEventsCallback(response) {
                // Check the recurrence of the first event.
                if (response[0].recurrence == bondi.pim.calendar.NO_RECURRENCE) {
                        alert("This event takes place once");
                }
        }

        // Define an error callback.
        function failureGetEventsCallback(response) {
                alert("Error: "+response.code);
        }

        // Find all events in the calendar (no filter is specified).
        var event = calendar.findEvents(successGetEventsCallback,failureGetEventsCallback,null);

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/pim.calendar

All the Calendar features

Includes API features:

  • http://bondi.omtp.org/api/pim.calendar.read
  • http://bondi.omtp.org/api/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 .calendarManager.

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

Calls to read calendars

Device capabilities:

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

Call to create, update or delete events from calendar.

Device capabilities:

  • pim.event.write

1.3. Device capabilities

pim.event.write

Writes events into the terminal storage

pim.event.read

Read contacts 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 succesfully

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

3.2. CalendarManager

Master event management interface 

        interface CalendarManager {

                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;
                



                CalendarArray getCalendars()
                        raises(SecurityError);
        };

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

Code example
        // Define a success callback.
        function successFunc(response) {
                alert("bondi.pim.calendar loaded");
        }

        // Define an error callback.
        function failureFunc(response) {
                alert("bondi.pim.calendar load error");
        }

        // Request the calendar feature.
        bondi.requestFeature(successFunc, failureFunc, "pim.calendar");

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

Methods

getCalendars

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

Signature
CalendarArray getCalendars();
Return value
An Array of Calendar objects for each calendar available on the device. First position [0] will be assigned to the native calendar.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

API features
http://bondi.omtp.org/api/pim.calendar.read
Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var nativeCalendar = calendars[0];

3.3. Calendar

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

        interface Calendar {

                Event createEvent([Optional] in EventOptions options)
                        raises(SecurityError, DeviceAPIError);

                void addEvent(in Event event)
                        raises(SecurityError, DeviceAPIError);

                void updateEvent(in Event event)
                        raises(SecurityError, DeviceAPIError);

                void deleteEvent(in Event event)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation clearEvents(in SuccessCallback successCallback,
                                             in ErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation findEvents(in SuccessCallback successCallback,
                                            in ErrorCallback errorCallback,
                                            [Optional]in EventFilter filter)
                        raises(SecurityError, DeviceAPIError);
        };

This interface provide methods to: Find events using a key-value filter. Keys supported by this method are returned by the getSupportedPropertyKey method of the event class 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.

Code example
        // Define the success callback.
        function successCallback(response) {
                alert("bondi.pim.calendar loaded correctly");
        }

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

        // Request the pim.calendar feature.
        bondi.requestFeature(successCallback, errorCallback, "pim.calendar");

Methods

createEvent

Creates an event object.

Signature
Event createEvent(in EventOptions 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
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR If any argument passed to the function is wrong If an invalid value is passed as recurrence argument see recurrence supported const If invalid value is passed as date argument

API features
http://bondi.omtp.org/api/pim.calendar.write
Code example
        // Get the calendar list.
        var calendars = bondi.pim.calendar.getCalendars();

        // 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' });
addEvent

Adds an event to the calendar.

Signature
void addEvent(in Event event);
Parameters
  • event: An Event object for the event to be added.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    NOT_SUPPORTED_ERROR if the event to be created will clash with a existing event in the same calendar.

    INVALID_ARGUMENT_ERROR if the event is wrong

API features
http://bondi.omtp.org/api/pim.calendar.write
Code example
        var calendars = bondi.pim.calendar.getCalendars();

        // Create an event.
        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 it to the calendar.
        calendars[0].addEvent(event);
updateEvent

Updates an existing event in the calendar.

Signature
void updateEvent(in Event event);
Parameters
  • event: An Event object for the event to be updated.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the event is wrong or if another any argument passed is wrong

API features
http://bondi.omtp.org/api/pim.calendar.write
Code example
        var calendars = bondi.pim.calendar.getCalendars();

        // Define a success callback.
        function successCallback(response) {
                // Update the location of the first event.
                response[0].location = "New location";
                calendars[0].updateEvent(response[0]);
        }

        // Define an error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", ocurred finding events");
        }

        // Find all events in the first calendar.
        calendars[0].findEvents(successCallback, errorCallback, null);
deleteEvent

Deletes the given event from the calendar.

Signature
void deleteEvent(in Event event);
Parameters
  • event: an Event object identifying the event.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the event is wrong or if another any argument passed is wrong

API features
http://bondi.omtp.org/api/pim.calendar.write
Code example
        // Get the list of all calendars.
        var calendars = bondi.pim.calendar.getCalendars();

        // Define the success callback.
        function successCallback(response) {
                // Delete the first event.
                calendars[0].deleteEvent(response[0]);
        }

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

        // Find all events in the first calendar.
        calendars[0].findEvents(successCallback, errorCallback, null);
clearEvents

Deletes all events in the calendar. This is an asynchronous method.

Signature
PendingOperation clearEvents(in SuccessCallback successCallback, in ErrorCallback errorCallback);
Parameters
  • successCallback: function called when the invocation ends succesfully.
  • 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.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the event is wrong or if another any argument passed is wrong

API features
http://bondi.omtp.org/api/pim.calendar.write
Code example
        var calendars = bondi.pim.calendar.getCalendars();

        // Define a success callback.
        function successCallback(response) {
                alert("Events cleared successfully!");
        }

        // Define an error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", ocurred clearing the calendar events");
        }

        // Clear all events in the first calendar.
        calendars[0].clearEvents(successCallback, errorCallback);
findEvents

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

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

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends succesfully, 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, string attributes are case insensitive
Return value
PendingOperation in order to cancel the async call
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the event is wrong or if another any argument passed is wrong

API features
http://bondi.omtp.org/api/pim.calendar.read
Code example
        var calendars = bondi.pim.calendar.getCalendars();

        // Define a success callback.
        function successCallback(response) {
                alert(response.length + " results found.");
        }

        // Define an error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", ocurred finding events");
        }

        // Find all events with a location of 'Huesca'.
        calendars[0].findEvents(successCallback, errorCallback, {location:"Huesca"} );

3.4. Event

Event object Abstraction of a device event. This interface offers properties 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. 

        interface Event {
                attribute DOMString id;

                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;


                Object getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);

                 StringArray getSupportedPropertyKeys();


                 void setProperty(in DOMString propertyName,in Object propertyValue)
                        raises(DeviceAPIError);
        };

Attributes

DOMString id

Unique identifier assigned to the event in the platform. Read only.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        var id = event.id;
DOMString description

Description of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.description = "BONDI Codefest";
DOMString summary

Summary of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.summary = "Launching the BONDI reference implementation";
Date startTime

Starttime of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.startTime = new Date(2009, 3, 30, 9, 0);
Date endTime

Sets the end time of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.endTime = new Date(2009, 3, 30, 11, 0);
DOMString location

Location of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.location = "Huesca";
unsigned short recurrence

Recurrence of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.recurrence = bondi.pim.calendar.NO_RECURRENCE;
DOMString status

Status of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.status = bondi.pim.calendar.TENTATIVE_STATUS;
Date alarmDate

Event alarm date

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
  event.alarmDate = new Date(2009, 3, 30, 11, 0);
unsigned long alarmType

Event Alarm Type

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var event = calendar.CreateEvent(null);
        event.alarmType = bondi.pim.calendar.NO_ALARM;

Methods

getProperty

Gets the value of any of the Event object properties.

Signature
Object getProperty(in DOMString propertyName);
Parameters
  • propertyName: String containing the name of the property to be queried.
Return value
Object that contains the retrieved property
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR If the event or any another argument passed is wrong. If property passed as parameter is not supported. Properties supported may be returned using the getSupportedPropertyKeys method

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        calendar.findEvents(successCallback, errorCallback,null);

        function successCallback(response) {
                var event = response[0];
                var location = event.getProperty("location");
                alert(location);
        }

        function errorCallback(response) {
                alert("Error: "+ response.code);
        }
getSupportedPropertyKeys

Gets the names of all the supported properties for the event object.

Signature
StringArray getSupportedPropertyKeys();
Return value
Array of Strings containing the event properties for this implementation. I.e. {"location", "subject"...}
Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var attributes = calendars[0].getSupportedPropertyKeys();
        alert("Number of attributes: " + attributes.length());
setProperty

Sets the value of a Event object property.

Signature
void setProperty(in DOMString propertyName, in Object propertyValue);
Parameters
  • propertyName: String containing the name of the property to be set.
  • propertyValue: String containing the value of the property to be set.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR If the event is wrong if propertyName is not supported If propertyValue is not the correct data type for the property

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];

        // Define a success callback.
        function successCallback(response)
        {
                // Set a new location on the first event.
                var event = response[0];
                var location = "Tramacastilla de Tema";
                event.setProperty("location", location);
        }

        // Define an error callback.
        function errorCallback(response)
        {
                alert("Error: "+ response.code);
        }

        // Get all events.
        var operation = calendar.findEvents(successCallback, errorCallback,null);

3.5. EventOptions

Interface used for event creation 

        [NoInterfaceObject, Callback] interface EventOptions {
              
     attribute DOMString summary;
       
     attribute DOMString description;
         
     attribute DOMString location;
        
     attribute Date startTime;
         
     attribute Date endTime;
      
     attribute short recurrence;
        
     attribute unsigned short status;
                  
     attribute Date alarmDate;
         
     attribute unsigned short alarmType;
   };

This interface is intended to be used for input parameters for event creation (createEvent). All the attributes are optional and by default are undefined

Code example
        // Get the calendar list.
        var calendars = bondi.pim.calendar.getCalendars();

        // 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' });

Attributes

DOMString summary

Event summary

DOMString description

Description of the event.

DOMString location

Location of the event.

Date startTime

Event starting time.

Date endTime

Event end time.

short recurrence

Recurrence of the event.

unsigned short status

Status of the event.

Date alarmDate

Date in which the user will be notified about the event

unsigned short alarmType

Type of alarm.

3.6. EventFilter

Interface used for event filtering 

        [NoInterfaceObject, Callback] interface EventFilter {
              
     attribute DOMString summary;
       
     attribute DOMString description;
         
     attribute DOMString location;
        
     attribute Date initialStartTime;
         
     attribute Date finalStartTime;
         
     attribute Date initialEndTime;
      
     attribute Date finalEndTime;
      
     attribute short recurrence;
        
     attribute unsigned short status;
                  
     attribute Date initialAlarmDate;
         
     attribute Date finalAlarmDate;
         
     attribute unsigned short alarmType;
  };

This interface is intended to be used for input parameters for event searching (findEvents). All the attributes are optional and by default are undefined

Code example
        var calendars = bondi.pim.calendar.getCalendars();

        // Define a success callback.
        function successCallback(response) {
                alert(response.length + " results found.");
        }

        // Define an error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", ocurred finding events");
        }

        // Find all events with a location of 'Huesca'.
        calendars[0].findEvents(successCallback, errorCallback, {location:"Huesca"} );

Attributes

DOMString summary

Event summary

DOMString description

Description of the event.

DOMString location

Location of the event.

Date initialStartTime

Minimum Event starting time.

Date finalStartTime

Maximum Event starting time.

Date initialEndTime

Minimum Event end time.

Date finalEndTime

Maximum Event end time.

short recurrence

Recurrence of the event.

unsigned short status

Status of the event.

Date initialAlarmDate

Minimum date in which the user will be notified about the event

Date finalAlarmDate

Maximum date in which the user will be notified about the event

unsigned short alarmType

Type of alarm.

3.7. CalendarManagerObject

Specifies what is instantiated at feature request 

        interface CalendarManagerObject {
                readonly attribute CalendarManager calendarManager; 
        };