Bondi logo

The Bondi Calendar Module: bondi.pim.calendar - Version 1.0

28 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(Map options)
void addEvent(Event evt)
void updateEvent(Event evt)
void deleteEvent(Event evt)
PendingOperation clearEvents(BONDISucessCallback successCallback, ErrorCallback errorCallback)
PendingOperation findEvents(BONDISucessCallback successCallback, ErrorCallback errorCallback, Map filter)
EventObject getProperty(DOMString propertyName)
StringArray getSupportedPropertyKeys()
void setProperty(DOMString propertyName, Object propertyValue)

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

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

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

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

1.1. 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 provided is provided.

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.2. 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. CalendarsArray

Array of Calendars. 

        typedef sequence<Calendar> CalendarsArray;

3. Interfaces

3.1. EventsArraySuccessCallback

Success callback for retrieving a list of calendar events. 

        [Callback] interface EventsArraySuccessCallback {
                void onSuccess(in EventsArray obj);
        };

Success callback that takes an array of Events as input argument. It is used in the asynchronous operation to get a list of Events.

3.2. CalendarManager

Master event management interface 

        interface CalendarManager {

                const short NO_RECURRENCE  = 0;

                const short DAILY_RECURRENCE = 1;

                const short WEEKLY_RECURRENCE = 2;

                const short MONTHLY_RECURRENCE = 3;

                const short YEARLY_RECURRENCE = 4;

                CalendarArray getCalendars()
                        raises(SecurityError, DeviceAPIError);
        };

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
        // Request the calendar feature.
        bondi.requestFeature(successFunc, failureFunc, "pim.calendar");

        function successFunc(response) {
                alert("bondi.pim.calendar loaded");
        }

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

Constants

short NO_RECURRENCE

The calendar entry occurs once

short DAILY_RECURRENCE

The calendar entry occurs every day

short WEEKLY_RECURRENCE

The calendar entry occurs every week

short MONTHLY_RECURRENCE

The calendar entry occurs every month

short YEARLY_RECURRENCE

The calendar entry occurs every year

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 modeling 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.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if any argument passed to the function is wrong
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 Map options)
                        raises(SecurityError, DeviceAPIError);

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

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

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

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

                PendingOperation findEvents(in BONDISucessCallback successCallback,
                                            in ErrorCallback errorCallback,
                                            [Optional]in Map 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
        bondi.requestFeature(successCallback, errorCallback, "bondi.pim.calendar");
        function successCallback(response) {
                alert("bondi.pim.calendar loaded correctly");
        }
        function errorCallback(response) {
                alert("Error: " + response.code);
        }

Methods

createEvent

Creates an event object.

Signature
Event createEvent(Map options);
Parameters
  • options: an associative array containing the event data
    The options map can take the following keys:
    - "description" : String. Description of the Event.
    - "summary" : String. Representing the event summary.
    - "starTime" : String. Representing the event start time.
    - "endTime": Date. Representing the event start time.
    - "location": Date. Location where the event will succeed.
    - "recurrence": short. Any of the constans defined in the CalendarManager refering to the recurrence. Accepted values from 0 to 4.
    Supported properties also are returned by the getSupportedPropertyKeys event method.
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
        var calendars = bondi.pim.calendar.getCalendars();

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

Adds an event to the calendar.

Signature
void addEvent(Event evt);
Parameters
  • evt: An Event object modeling 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 evt = calendars[0].createEvent({description:'BONDI Codefest', summary:'foo', startTime: new Date(2009, 3, 30, 10, 00), endTime: new Date(2009, 3, 30, 11, 00), location:'Huesca' });

        // Add it to the calendar.
        calendars[0].addEvent(evt);
updateEvent

Updates an existing event in the calendar.

Signature
void updateEvent(Event evt);
Parameters
  • evt: An Event object modeling the event to be updated.
Return value
void.
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();
        calendars[0].findEvents(successCallback, errorCallback, null);

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

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

Deletes the given event from the calendar.

Signature
void deleteEvent(Event evt);
Parameters
  • evt: an Event object identifying the event.
Return value
void.
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();

        calendars[0].findEvents(successCallback, errorCallback);

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

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

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

Signature
PendingOperation clearEvents(BONDISucessCallback successCallback, 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();
        calendars[0].clearEvents(successCallback, errorCallback);

        function successCallback(response) {
                alert("Events cleared successfully!");
        }

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

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

Signature
PendingOperation findEvents(BONDISucessCallback successCallback, ErrorCallback errorCallback, Map 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: Array of key-value pairs acting as a filter for searching.
    The filter map can take the following keys:
    - "description" : String. Description of the Event.
    - "summary" : String. Representing the event summary.
    - "starTime" : String. Representing the event start time.
    - "endTime": Date. Representing the event start time.
    - "location": Date. Location where the event will succeed.
    - "recurrence": short. Any of the constans defined in the CalendarManager refering to the recurrence. Accepted values from 0 to 4.
    Supported properties also are returned by the getSupportedPropertyKeys event method.
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();

        // Find all events with a location of 'Huesca'.
        calendars[0].findEvents(successCallback, errorCallback, {location:"Huesca"} );
                 
        function successCallback(response) {
                alert(response.length + " results found.");
        }

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

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 findEvents filter, 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;

                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 calenda r= calendars[0];
        var evt = calendar.CreateEvent(null);
        var id = evt.id;
DOMString description

Description of the event.

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

Summary of the event.

Code example
        var calendars = bondi.pim.calendar.getCalendars();
        var calendar = calendars[0];
        var evt = calendar.CreateEvent(null);
        evt.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 evt = calendar.CreateEvent(null);
        evt.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 evt = calendar.CreateEvent(null);
        evt.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 evt = calendar.CreateEvent(null);
        evt.location = "Huesca";
unsigned short recurrence

Recurrence of the event.

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

Methods

getProperty

Gets the value of any of the Event object properties.

Signature
Object getProperty(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 evt = response[0];
                var location = evt.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(DOMString propertyName, 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];
        var operation = calendar.findEvents(successCallback, errorCallback,null);
        function successCallback(response)
        {
                var evt = response[0];
                var location = "Tramacastilla de Tema";
                evt.setProperty("location", location);
        }

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