Bondi logo

The Bondi task Module - Version 1.1

February 2010

Authors

© 2009-2010 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)
TaskListArraySuccessCallbackvoid onSuccess(TaskListArray taskLists)
TaskManagerPendingOperation getTaskLists(TaskListArraySuccessCallback successCallback, ErrorCallback errorCallback)
TaskListTask createTask(TaskProperties options)
PendingOperation addTask(SuccessCallback successCallback, ErrorCallback errorCallback, Task task)
PendingOperation updateTask(SuccessCallback successCallback, ErrorCallback errorCallback, Task task)
PendingOperation deleteTask(SuccessCallback successCallback, ErrorCallback errorCallback, Task task)
PendingOperation findTasks(TaskArraySuccessCallback successCallback, ErrorCallback errorCallback, TaskFilter filter)
Task
TaskProperties
TaskFilter
TaskManagerObject

1. Introduction

Copyright 2010 OMTP Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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

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/1.1/pim.task

All the Task features

Includes API features:

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

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

Call to getTaskLists method of TaskManager class.

Device capabilities:

  • pim.task.read
http://bondi.omtp.org/api/1.1/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 tasks with a Task list. 

        [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 Tasks.

Methods

onSuccess

Method invoked when the list of tasks within a task list are retrieved successfully

Signature
void onSuccess(in TaskArray tasks);
Parameters
  • tasks: Tasks within a task list.

3.2. TaskListArraySuccessCallback

Success callback for retrieving all Task Lists. 

        [Callback=FunctionOnly, NoInterfaceObject] interface TaskListArraySuccessCallback {
                void onSuccess(in TaskListArray taskLists);
        };

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

Methods

onSuccess

Method invoked when tasks lists are retrieved successfully

Signature
void onSuccess(in TaskListArray taskLists);
Parameters
  • taskLists: Task lists

3.3. TaskManager

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

        [NoInterfaceObject] interface TaskManager {

                PendingOperation getTaskLists(in TaskListArraySuccessCallback successCallback,
                                in ErrorCallback errorCallback);
        };

Methods

getTaskLists

Gets the available task lists in the device.

Signature
PendingOperation getTaskLists(in TaskListArraySuccessCallback successCallback, in ErrorCallback errorCallback);

This is an asynchronous method.

If no Task List is available the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.contact.read
Code example
        // Define the success callback.
        function taskListSuccessCallback(taskLists) {
                // do something with resulting task lists
        }

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

        // Get a list of available task lists.
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);

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

        [NoInterfaceObject] interface TaskList {
                const unsigned short SIM_TASK_LIST = 0;

                const unsigned short DEVICE_TASK_LIST = 1;


                readonly attribute unsigned short type;

                readonly attribute DOMString name;

                Task createTask([Optional] in TaskProperties options)
                        raises(DeviceAPIError);

                PendingOperation addTask(in SuccessCallback successCallback,
                                                     in ErrorCallback errorCallback,
                                                     in Task task);

                PendingOperation updateTask(in SuccessCallback successCallback,
                                        in ErrorCallback errorCallback,
                                        in Task task);

                PendingOperation deleteTask(in SuccessCallback successCallback,
                                        in ErrorCallback errorCallback,
                                        in Task task);

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

Constants

unsigned short SIM_TASK_LIST

Constant used to identify SIM Task Lists.

unsigned short DEVICE_TASK_LIST

Constant used to identify Device Task Lists.

Attributes

readonly unsigned short type

Task List Type Read only.

It MUST be one of the below constants:

  • SIM_TASK_LIST = 0
  • DEVICE_TASK_LIST = 1
Code example
        // Define the success callback.
        function taskListSuccessCallback(tasklists) {
          alert("The task list type is " + tasklists[0].type);  
        }

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

        // Get a list of available task lists 
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);
readonly DOMString name

Task List Human Readable Name Read only.

Code example
        // Define the success callback.
        function taskListSuccessCallback(tasklists) {
          alert("The task list name is " + taskLists[0].name);  
        }

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

        // Get a list of available task lists 
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);

Methods

createTask

Creates a task object.

Signature
Task createTask(in TaskProperties options);
Parameters
  • options: Task Information
Return value
The created task object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the options are wrong

Code example
        // Define the success callback.
        function taskListSuccessCallback(taskLists) {
                // Create a new task.
                var task = taskLists[0].createTask({priority:0, summary:'blah blah blah', note: 'ask pedro', dueDate:'2009-02-20T09:00:00.000+01:00', status:0});
        }

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

        // Get a list of available task lists.
        bondi.pim.task.getTaskLists(taskListSuccessCallback, errorCallback);
addTask

Adds a task to the task list.

Signature
PendingOperation addTask(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Task task);

This is an asynchronous method.

If the task is successfully added, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • task: The task object to be added in the terminal storage
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.task.write
Code example
        // Define the task lists success callback.
        function taskListSuccessCallback(taskLists) {
                // Create a new task.
                var task = taskLists[0].createTask({priority:0, summary:'blah blah blah', note: 'ask pedro', dueDate:'2009-02-20T09:00:00.000+01:00', status:0});

                // Add new task to tasklist 0.
                tasklists[0].addTask(taskAddSuccessCallback, errorCallback, task);
        }

        // Define the task success callback.
        function taskAddSuccessCallback(response) {
                alert("Task added successfully");
        }

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

        // Get a list of available task lists.
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);
updateTask

Updates an existing task in the task list.

Signature
PendingOperation updateTask(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Task task);

This is an asynchronous method.

If the task is successfully updated, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • task: The task object to be updated
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.task.write
Code example
        var myTaskList;

        // Define the task lists success callback.
        function taskListSuccessCallback(taskLists) {
                myTaskList = taskLists[0];

                // Find all tasks in Task List 0.
                myTaskList.findTasks(taskSearchSuccessCallback, errorCallback, null);
        }

        // Define the task success callback.
        function taskSearchSuccessCallback(tasks) {
                tasks[0].note = "New Note";
                // Update the first existing task.
                myTaskList.updateTask(taskUpdateSuccessCallback, errorCallback, tasks[0]);
        }

        // Define the task success callback.
        function taskUpdateSuccessCallback(response) {
                alert("Updated");
        }

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

        // Get a list of available task lists.
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);
deleteTask

Deletes a task from the task list.

Signature
PendingOperation deleteTask(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Task task);

This is an asynchronous method.

If the task is successfully deleted, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • task: The task object to be deleted
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/pim.task.write
Code example
        var myTaskList;

        // Define the task lists success callback.
        function taskListSuccessCallback(taskLists) {
                myTaskList = taskLists[0];

                // Find all tasks in Task List 0.
                myTaskList.findTasks(taskSearchSuccessCallback, errorCallback, null);
        }

        // Define the task success callback.
        function taskSearchSuccessCallback(tasks) {
                // Delete the first existing task.
                myTaskList.deleteTask(taskDeleteSuccessCallback, errorCallback, tasks[0]);
        }

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

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

        // Get a list of available task lists.
        bondi.pim.task.getTaskLists(taskListSuccessCallback,errorCallback);
findTasks

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

Signature
PendingOperation findTasks(in TaskArraySuccessCallback successCallback, in ErrorCallback errorCallback, in TaskFilter filter);

This is an asynchronous method.

The filtering is implemented according to the design patterns (chapter 2.4). If no filter is passed all the tasks will be returned.

If the method is successfully executed, the SuccessCallback is invoked.

If no task is available in the task list the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

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
API features
http://bondi.omtp.org/api/1.1/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.5. Task

Abstraction of a 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. 

        [NoInterfaceObject] interface Task : TaskProperties {

                readonly attribute DOMString id;
        };

Attributes

readonly DOMString id

Unique identifier assigned to the task in the platform.

Read only.

Code example
        var task = tasklist.createTask();
        alert(task.id);

3.6. TaskProperties

Interface used for task creation. 

        [NoInterfaceObject] interface TaskProperties {

                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;

                attribute unsigned short priority;

                attribute DOMString note;

                attribute DOMString summary;

                attribute Date dueDate;

                attribute unsigned short status;
        };

This interface is intended to be used for input parameters for task creation (createTask).

It includes methods to get a specific property and to set the available properties to use in the findTasks filter, addTask and updateTask methods.

All the attributes are optional and by default are undefined.

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.

Attributes

unsigned short priority

Priority of the task.

Code example
        var task = taskList.createTask();
        task.priority = bondi.pim.task.HIGH_PRIORITY;
DOMString note

Note of the task.

Code example
        var task = taskList.createTask();
        task.note = "BONDI note";
DOMString summary

Summary of the task.

Code example
        var task = taskList.createTask();
        task.summary = "BONDI Codefest summary";
Date dueDate

Due date of the task.

Code example
        var task = taskList.createTask();
        task.dueDate = '2009-02-20T09:00:00.000+01:00';
unsigned short status

Completed status of the task.

Code example
        var task = taskList.createTask();
        task.status = bondi.pim.task.STATUS_PENDING;

3.7. TaskFilter

Interface used to create Filter objects following the Task structure. 

   [NoInterfaceObject] interface TaskFilter : GenericFilter {
   };

3.8. TaskManagerObject

Specifies what is instantiated at feature request 

        interface TaskManagerObject {
                readonly attribute TaskManager task; 
        };