Using +platform services

The S60 platform allows widgets installed +on S60 mobile devices to:

Access +and launch applications on a device using the AppManager +Service API
Access +and manage calendar information using the Calendar +Service API
Access +and manage information about contacts using the Contacts +Service API
Access +and manage information about landmarks using the Landmarks +Service API
Access +device logging events using the Logging +Service API
Access +device location information and perform location-based calculations using +the Location Service +API
Access +information about media files stored on a device using the Media +Management Service API
Send, +retrieve, and manage messages such as SMS and MMS using the Messaging +Service API
Access +data from the physical sensors of a device using the Sensor +Service API
Access +and modify system information on a device using the SystemInfo +Service API of WRT 1.1
+
Access +system information and control certain device features using the SystemInfo Service API of +WRT 1.0

The Service APIs are supported since WRT 1.1.

+ +

Using S60 Platform Services and Service +APIs

Widgets use the S60 Platform Services through JavaScript +Service APIs provided by the Web Runtime environment. Programming a +widget to access a service through its Service API involves two steps:

Create a service +object (an object for calling the Service API) using the getServiceObject() factory method provided by the device object. +This method uses a service provider name and an interface name to create the +appropriate service object:
+ +
```
var so = device.getServiceObject(provider, interface);
```
+
Each Service API has a service provider name and supports one interface. +The service provider name identifies the Service API while the interface defines +a set of common methods for service objects.
+
For example, the service provider name for the Calendar +Service API is Service.Calendar and the supported +interface is IDataSource. To create a Calendar service +object, use the following code:
+
```
var so = device.getServiceObject("Service.Calendar", "IDataSource");
```
+ +
Use the service +object to call the Service API. The calls to the Service API are made through +the supported interface, since it provides the necessary methods.
+ +
For example, the IDataSource interface defines +the GetList() method, which returns an object as its +return value. To make a GetList() call with the Calendar +service object created above, use the following code:
+
```
var result = so.IDataSource.GetList(criteria);
```
+ +

The only exception to the above is the SystemInfo Service API of WRT +1.0, which is a scriptable plug-in. For instructions on using this API, see +section JavaScript SystemInfo Service API (WRT 1.0).

Arguments and return values

Service API methods use JavaScript objects as arguments and return +values. Argument objects can contain primitive types and other objects. Return +value objects can contain primitive types, objects, arrays, and iterators. +A primitive type is a string, number, or boolean. An object is a type of JavaScript object. +It is a collection of properties. An array is a type of object that stores +values that can be primitive types or objects. These values are accessed by +indexing. An iterator is an object used to traverse through an ordered list +of objects. The getNext() method +on the iterator returns the next object in the ordered list.

+ + +

Creating objects in JavaScript

In JavaScript, you can create an object in three ways.

new() with dot notation syntax:

// example 1
+var criteria = new Object();
+criteria.Type = 'FileInfo';
+// example 2 - nested object
+var filter = new Object();
+filter.FileType = 'Sound'
+var criteria = new Object();
+criteria.Filter = filter;
+

Object literal syntax:

var criteria = { 'Type': 'FileInfo', 'Filter': { 'FileType': 'Sound' } };

new() with array syntax:

// example 1
+var criteria = new Object();
+criteria ['Type'] = 'FileInfo';
+// example 2 - nested object
+var filter = new Object();
+filter['FileType'] = 'Sound'
+var criteria = new Object();
+criteria ['Filter'] = filter;
+