The Bondi Task Module: bondi.pim.task - Version 1.0

28 May 2009

Authors

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

Abstract

To give API access to phone resident task management functions

1. Introduction
- 1.1. Features
- 1.2. Device Capabilities
2. Type Definitions
- 2.1. TaskListArray
3. Interfaces
- 3.1. TaskManager
- 3.2. TaskList
- 3.3. Task

Summary of Methods

Interface	Method
TaskManager	TaskListArray getTaskLists()
TaskList	Task createTask(Map options) void addTask(Task task) void updateTask(Task task) void deleteTask(Task task) PendingOperation clearTasks(SucessCallback successCallback, ErrorCallback errorCallback) PendingOperation findTasks(SucessCallback successCallback, ErrorCallback errorCallback, Map filter)
Task	Object getProperty(DOMString propertyName) StringArray getSupportedPropertyKeys() void setProperty(DOMString propertyName, Object propertyValue)

1. Introduction

The BONDI Task API provides access to the tasks stored in the device. With this API it is possible to read, create, delete and update tasks.

It is also possible to assign priority to tasks with the following supported values:
- HIGH_PRIORITY
- MEDIUM_PRIORITY
- LOW_PRIORITY

The status of the task can be defined depending on the platform. The supported values are:
- STATUS_DONE
- STATUS_PENDING
- STATUS_ONGOING

Finding tasks using a filter is also supported with the method findTask. The supported properties are returned by the task class method getSupportedPropertyKeys. These supported keys are valid for this and/or the createTask method.

Code example

        var taskList = bondi.pim.task.getTaskLists();
        var tasks = taskList[0].findTasks(successCallback,errorCallback,null);
        function successCallback(response) {
                if (response[0].priority == bondi.pim.task.HIGH_PRIORITY) alert("Very important");
        }
        function errorCallback(response){alert("Error retrieving task, because: " + 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.task.read: Call to getTaskLists method of TaskManager class.

Device capabilities: pim.task.read

http://bondi.omtp.org/api/pim.task.write: Call to addTask, updateTask, deleteTask, clearTasks methods of TaskList class.

Device capabilities: pim.task.write

1.2. Device capabilities

pim.task.read: Read tasks
pim.task.read: Write, modify or delete tasks

2. Type Definitions

2.1. `TaskListArray`

Array of Tasks.

        typedef sequence<TaskList> TaskListArray;

3. Interfaces

3.1. `TaskManager`

Manager class exposed as the task module API. The Task Manager interface offers methods to retrieve the task lists, stored in the phone.

        interface TaskManager {

                const unsigned short HIGH_PRIORITY = 0;

                const unsigned short MEDIUM_PRIORITY = 1;

                const unsigned short LOW_PRIORITY = 2;

                const unsigned short STATUS_DONE = 0;

                const unsigned short STATUS_PENDING = 1;

                const unsigned short STATUS_ONGOING = 2;

                TaskListArray getTaskLists()
                        raises(SecurityError);
        };

Constants

unsigned short HIGH_PRIORITY: High priority
unsigned short MEDIUM_PRIORITY: Medium priority.
unsigned short LOW_PRIORITY: Low priority.
unsigned short STATUS_DONE: The task has been finished.
unsigned short STATUS_PENDING: The task has not been started yet.
unsigned short STATUS_ONGOING: The task has been started but it is no finished yet.

Methods

getTaskLists

Gets the available task lists in the device.

Signature

TaskListArray getTaskLists();

Return value

An array of TaskList objects modelling each task list available in the device. First position [0] will be assigned to the native task list

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.

API features

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

Code example

        var tasklists = bondi.pim.task.getTaskLists();
        var nativeTaskList = tasklists[0];

3.2. `TaskList`

Abstraction of a list of tasks A list representing all tasks available in the device The TaskList interface offers methods to Find tasks using filters with the findTask method. Adds a task on the device using the addTask method. Update an existing task using the updateTask method. Delete a specific task using the deleteTask method. Clear the entire task list using the clearTasks method.

        interface TaskList {
                Task createTask([Optional] in Map options)
                        raises(SecurityError, DeviceAPIError);

                void addTask(in Task task)
                        raises(SecurityError, DeviceAPIError);

                void updateTask(in Task task)
                        raises(SecurityError, DeviceAPIError);

                void deleteTask(in Task task)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation clearTasks(in SucessCallback successCallback,
                                            in ErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation findTasks(in SucessCallback successCallback,
                                           in ErrorCallback errorCallback,
                                           [Optional] in Map filter)
                        raises(SecurityError, DeviceAPIError);
        };

Methods

createTask

Creates a task object.

Signature

Task createTask(Map options);

Parameters

options: optional map containing an associative array to create the task
The option map can take the following keys:
- "priority" : Short. Any of the constants defined in the TaskListManager refering to the task priority. Accepted values from 0 to 2
- "notes" : String. The task description note.
- "summary" : String. Summary of the task.
- "due" : Date: Datetime when the taks will be done.
- "status" : Short. Any of the constans defined in the TaskListManager refering to the task status. Accepted values from 0 to 2.
Supported properties also are returned by the getSupportedPropertyKeys task method.

Return value

The created task object.

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: INVALID_ARGUMENT_ERROR if the options are wrong.

API features

http://bondi.omtp.org/api/pim.task.write

Code example

        var tasklists = bondi.pim.task.getTaskLists();
        var task = tasklists[0].createTask({priority:0, summary:'blah blah blah', note: 'ask pedro', due:'2009-02-20T09:00:00.000+01:00', status:0});

addTask

Adds a task to the task list.

Signature

void addTask(Task task);

Parameters

task: The task object to be added in the terminal storage

Return value

void

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: INVALID_ARGUMENT_ERROR if the input parameter contains a wrong object.

API features

http://bondi.omtp.org/api/pim.task.write

Code example

        var tasklists = bondi.pim.task.getTaskLists();
        var task = tasklists[0].createTask({priority:0, summary:'a quick reminder', note: 'ask pedro', due:'2009-02-20T09:00:00.000+01:00', status:0});
        tasklists[0].addTask(task);

updateTask

Updates an existing task in the task list

Signature

void updateTask(Task task);

Parameters

task: The Task object to be updated

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: INVALID_ARGUMENT_ERROR if task are wrong object.

API features

http://bondi.omtp.org/api/pim.task.write

Code example

        var taskLists = bondi.pim.task.getTaskLists();
        taskLists[0].findTasks(successCallback,errorCallback,null);

        function successCallback(response) {
                response[0].note = "updated note";
                taskLists[0].updateTask(response[0]);
        }

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

deleteTask

Deletes a task from the task list.

Signature

void deleteTask(Task task);

Parameters

task: The Task object to be deleted

Return value

void

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: INVALID_ARGUMENT_ERROR if task are wrong object.

API features

http://bondi.omtp.org/api/pim.task.write

Code example

        var taskLists = bondi.pim.task.getTaskLists();
        ...
        taskLists[0].deleteTask(task);

clearTasks

Deletes all tasks in the task list. It is an asynchronous method.

Signature

PendingOperation clearTasks(SucessCallback successCallback, ErrorCallback errorCallback);

Parameters

successCallback:
errorCallback:

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 task are wrong object.

API features

http://bondi.omtp.org/api/pim.task.write

Code example

        var taskLists = bondi.pim.task.getTaskLists();
        taskLists[0].clearTasks(null, successCallback, errorCallback);

        function successCallback(response) {
                alert("Deleted!");
        }

        function errorCallback(response) {
                alert( "The following error: " +  response.message + ", occurred in " + response.name);
        }

findTasks

Gets an array of Task objects for tasks stored within the calendar and matching the selected filter. This is an asynchronous method.

Signature

PendingOperation findTasks(SucessCallback 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.

Parameters

successCallback: function called when the invocation ends successfully.
errorCallback: function called when an error occurs, the input parameter "response" is an DeviceAPIError object with error code giving information about the type of error that occurred.
filter: Associative Array with the search criteria, every simple type property is supported
The filter map can take the following keys:
- "priority" : Short. Any of the constants defined in the TaskListManager refering to the task priority. Accepted values from 0 to 2
- "notes" : String. The task description note.
- "summary" : String. Summary of the task.
- "due" : String: Datetime when the taks will be done.
- "status" : Short. Any of the constans defined in the TaskListManager refering to the task status. Accepted values from 0 to 2.
Supported properties also are returned by the getSupportedPropertyKeys task 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 filter or options are wrong.

API features

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

Code example

        var taskLists = bondi.pim.task.getTaskLists();
        taskLists[0].findTasks(successCallback, errorCallback, {summary:"Add BONDI comments"});

        function successCallback(response) {
                alert(response.length + " results found.");
        }

        function errorCallback(response) {
                alert( "The following error: " +  response.message + ", occurred in " + response.name);
        }

3.3. `Task`

Abstaction of the task . This interface offers properties to manage each task property. It also includes methods to get a specific property and to get the available properties to use in the findTasks filter, addTask and updateTask methods.

        interface Task {

                attribute DOMString id;

                attribute unsigned short priority;

                attribute DOMString note;

                attribute DOMString summary;

                attribute Date due;

                attribute unsigned short status;

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

                StringArray getSupportedPropertyKeys()
                        raises(DeviceAPIError);

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

Attributes

DOMString id

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

Code example

        var task = tasklist.CreateTask(null);
        var id = task.id;

unsigned short priority

Priority of the task.

Code example

        var task = taskList.CreateTask(null);
        task.priority = bondi.pim.task.HIGH_PRIORITY;

DOMString note

Note of the task.

Code example

        var task = taskList.CreateTask(null);
        task.note = "BONDI note";

DOMString summary

Summary of the task.

Code example

        var task = taskList.CreateTask(null);
        task.summary = "BONDI Codefest summary";

Date due

Due date of the task.

Code example

        var task = taskList.CreateTask(null);
        task.due = '2009-02-20T09:00:00.000+01:00';

unsigned short status

Completed status of the task.

Code example

        var task = taskList.CreateTask(null);
        task.status = bondi.pim.task.STATUS_PENDING;

Methods

getProperty

Gets the value of any of the Task object properties.

Signature

Object getProperty(DOMString propertyName);

Parameters

propertyName: The property name to be returned

Return value

Object containing the retrieved property

Exceptions

DeviceAPIError: INVALID_ARGUMENT_ERROR if invalid propertyName is given

Code example

        ...
        var due = task.getProperty("due");

getSupportedPropertyKeys

Gets the available attributes for tasks in this task list.

Signature

StringArray getSupportedPropertyKeys();

Return value

Array of Strings containing the task properties for this implementation. I.e. {"priority", "note", "due", "summary", "status"}

Exceptions

DeviceAPIError: INVALID_ARGUMENT_ERROR if an invalid parameter is given

Code example

        var tasklists = bondi.pim.task.getTaskLists();
        var attributes = tasklists[0].getSupportedPropertyKeys();
        alert("Number of attributes: " + attributes.count);

setProperty

Sets the value of a Task object property.

Signature

void setProperty(DOMString propertyName, Object propertyValue);

Parameters

propertyName: The property name to be set
propertyValue: Value to be assigned to the property

Return value

void

Exceptions

DeviceAPIError: INVALID_ARGUMENT_ERROR if invalid propertyName is given

Code example

        var maxSize = task.getPropertyMaxSize("Summary");
        var summary = "Reformat BONDI comments within Doxygen documentation";
        task.setProperty("summary", summary.substring(0, maxSize-1));

The Bondi Task Module: bondi.pim.task - Version 1.0

28 May 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. TaskListArray

3. Interfaces

3.1. TaskManager

Constants

Methods

Signature

Return value

Exceptions

API features

Code example

3.2. TaskList

Methods

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

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

Signature

Parameters

Return value

Exceptions

API features

Code example

3.3. Task

Attributes

Code example

Code example

Code example

Code example

Code example

Code example

Methods

Signature

Parameters

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

2.1. `TaskListArray`

3.1. `TaskManager`

3.2. `TaskList`

3.3. `Task`