Bondi logo

The Bondi task Module - Version 1.1

26 October 2009

Authors

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

Abstract

To give API access to phone resident task management functions

Table of Contents

Summary of Methods

InterfaceMethod
TaskArraySuccessCallbackvoid onSuccess(TaskArray tasks)
TaskManagerTaskListArray getTaskLists()
TaskListTask createTask(TaskOptions options)
void addTask(Task task)
void updateTask(Task task)
void deleteTask(Task task)
PendingOperation clearTasks(SuccessCallback successCallback, ErrorCallback errorCallback)
PendingOperation findTasks(TaskArraySuccessCallback successCallback, ErrorCallback errorCallback, TaskFilter filter)
TaskObject getProperty(DOMString propertyName)
StringArray getSupportedPropertyKeys()
void setProperty(DOMString propertyName, Object propertyValue)
TaskOptions
TaskFilter
TaskManagerObject

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. 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.task

All the Task features

Includes API features:

  • http://bondi.omtp.org/api/pim.task.read
  • http://bondi.omtp.org/api/pim.task.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 TaskManager is instantiated, and the resulting object appears in the global namespace as .taskManager.

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.3. 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;

2.2. TaskArray

Array of Task. 

        typedef sequence<Task>     TaskArray;

3. Interfaces

3.1. TaskArraySuccessCallback

Success callback for retrieving a list of Task. 

        [Callback=FunctionOnly, NoInterfaceObject] interface TaskArraySuccessCallback {
                void onSuccess(in TaskArray tasks);
        };

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

Methods

onSuccess

Method invoked when the list of tasks is retrieved succesfully

Signature
void onSuccess(in TaskArray tasks);
Parameters
  • tasks: List of tasks

3.2. 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.3. 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 TaskOptions 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 SuccessCallback successCallback,
                                            in ErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError);

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

Methods

createTask

Creates a task object.

Signature
Task createTask(in TaskOptions options);
Parameters
  • options: Task Information
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(in Task task);
Parameters
  • task: The task object to be added in the terminal storage
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(in 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();

        // Define the success callback.
        function successCallback(response) {
                // Update the first task.
                response[0].note = "updated note";
                taskLists[0].updateTask(response[0]);
        }

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

        // Find the tasks.
        taskLists[0].findTasks(successCallback,errorCallback,null);
deleteTask

Deletes a task from the task list.

Signature
void deleteTask(in Task task);
Parameters
  • task: The Task object to be deleted
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(in SuccessCallback successCallback, in ErrorCallback errorCallback);
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.
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();

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

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

        // Clear all tasks.
        taskLists[0].clearTasks(successCallback, errorCallback);
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(in TaskArraySuccessCallback successCallback, in ErrorCallback errorCallback, in TaskFilter 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 conducted is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

The search is performed only taken into account the values that have been specified in the filter object

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: Task data to be used when filtering
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();

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

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

        // Find the tasks with the specified summary.
        taskLists[0].findTasks(successCallback, errorCallback, {summary:"Add BONDI comments"});

3.4. 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();


                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(in 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"}
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(in DOMString propertyName, in Object propertyValue);
Parameters
  • propertyName: The property name to be set
  • propertyValue: Value to be assigned to the property
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));

3.5. TaskOptions

Used for task filtering and task creation 

         [NoInterfaceObject, Callback]  interface TaskOptions {

        attribute short priority;

         attribute DOMString summary;

        attribute DOMString note; 

        attribute Date due;

        attribute short status;
    };

Contains task related information to be used for filtering purposes (in findTask method) or initialization (createTask method)

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

Attributes

short priority

Task priority

DOMString summary

Task summary

DOMString note

Task description

Date due

Task due date

short status

Task status

3.6. TaskFilter

Used for task filtering 

         [NoInterfaceObject, Callback]  interface TaskFilter {

        attribute short priority;

         attribute DOMString summary;

        attribute DOMString note; 

        attribute Date initialDueDate;

        attribute Date finalDueDate;

        attribute short status;
    };

Contains task related information to be used for filtering purposes (in findTask method)

Code example
        var taskLists = bondi.pim.task.getTaskLists();

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

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

        // Find the tasks with the specified summary.
        taskLists[0].findTasks(successCallback, errorCallback, {summary:"Add BONDI comments"});

Attributes

short priority

Task priority

DOMString summary

Task summary

DOMString note

Task description

Date initialDueDate

Initial task due date, used to look for tasks with due date later than the specified one

Date finalDueDate

Final task due date, used to look for tasks with due date previous to the specified one

short status

Task status

3.7. TaskManagerObject

Specifies what is instantiated at feature request 

        interface TaskManagerObject {
                readonly attribute TaskManager taskManager; 
        };