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;