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

27 July 2009

Authors

Guillermo Caudevilla Laliena <guillermo.caudevilla@vodafone.com>
Pedro Fraca Tarancon <pfracat@corp.vodafone.es>

Abstract

This module provides access to device calendars.

1. Introduction
- 1.1. Features
- 1.2. Device Capabilities
2. Type Definitions
- 2.1. EventsArray
- 2.2. CalendarArray
3. Interfaces
- 3.1. EventsArraySuccessCallback
- 3.2. CalendarManager
- 3.3. Calendar
- 3.4. Event

Summary of Methods

Interface	Method
EventsArraySuccessCallback	void onSuccess(EventsArray obj)
CalendarManager	CalendarArray getCalendars()
Calendar	Event createEvent(Map 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, Map filter)
Event	Object 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];

        // 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. 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. `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(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;

                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

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 Map 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 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

        // 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(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":unsigned 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

        // 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(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(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(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(SuccessCallback 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();

        // 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(SuccessCallback 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":unsigned 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();

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

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

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

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

27 July 2009

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

Code example

1.1. Features

1.2. Device capabilities

2. Type Definitions

2.1. EventsArray

2.2. CalendarArray

3. Interfaces

3.1. EventsArraySuccessCallback

Methods

Signature

Parameters

3.2. CalendarManager

Code example

Constants

Methods

Signature

Return value

Exceptions

API features

Code example

3.3. Calendar

Code example

Methods

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Exceptions

API features

Code example

Signature

Parameters

Exceptions

API features

Code example

Signature

Parameters

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

3.4. Event

Attributes

Code example

Code example

Code example

Code example

Code example

Code example

Code example

Methods

Signature

Parameters

Return value

Exceptions

Code example

Signature

Return value

2.1. `EventsArray`

2.2. `CalendarArray`

3.1. `EventsArraySuccessCallback`

3.2. `CalendarManager`

3.3. `Calendar`

3.4. `Event`