org.symbian.tools.wrttools.doc.WebDeveloper/html/GUID-46EABDC1-37CB-412A-ACAD-1A1A9466BB68.html
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="copyright" content="(C) Copyright 2009"/><meta name="DC.rights.owner" content="(C) Copyright 2009"/><meta name="DC.Type" content="mobileconcept"/><meta name="DC.Title" content="Using platform services"/><meta name="DC.Relation" scheme="URI" content="GUID-E3EA4F85-E0AE-42AB-8E51-EFD3F0E0A51E"/><meta name="DC.Relation" scheme="URI" content="GUID-85179E6B-E915-4D96-A5D1-D17D7C7180C7"/><meta name="DC.Relation" scheme="URI" content="GUID-1EFD7043-E9B8-4B4E-9EA6-A20B3EECC14A"/><meta name="DC.Format" content="XHTML"/><meta name="DC.Identifier" content="GUID-46EABDC1-37CB-412A-ACAD-1A1A9466BB68"/><title>Using
platform services </title><script type="text/javascript">
function initPage() {}
</script><link href="../PRODUCT_PLUGIN/book.css" rel="stylesheet" type="text/css"/><link href="css/s60/style.css" rel="stylesheet" type="text/css" media="all"/></head><body onload="initPage();"><div class="body"><div class="contentLeft prTxt"><h1 class="pageHeading" id="GUID-46EABDC1-37CB-412A-ACAD-1A1A9466BB68">Using
platform services</h1><div>
<p>The S60 platform allows <span>widgets</span> installed
on S60 mobile devices to:</p>
<p/>
<ul>
<li><p><a href="GUID-E092BF10-C076-4476-9E80-87919940201B.html#GUID-E092BF10-C076-4476-9E80-87919940201B">Access
and launch applications on a device</a> using the <a href="GUID-2D651505-F68C-4053-B565-9FF826C5B897.html#GUID-2D651505-F68C-4053-B565-9FF826C5B897">AppManager
Service API</a></p></li>
<li><p><a href="GUID-AE9A928B-F938-49B5-BC9E-72CB42046571.html#GUID-AE9A928B-F938-49B5-BC9E-72CB42046571">Access
and manage calendar information</a> using the <a href="GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4.html#GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4">Calendar
Service API</a></p></li>
<li><p><a href="GUID-662F2E2E-9538-42E5-9B5A-5664F1C11A9E.html#GUID-662F2E2E-9538-42E5-9B5A-5664F1C11A9E">Access
and manage information about contacts</a> using the <a href="GUID-A5853293-7B83-4CCE-9C29-B2B8F0CD8A18.html#GUID-A5853293-7B83-4CCE-9C29-B2B8F0CD8A18">Contacts
Service API</a></p></li>
<li><p><a href="GUID-D581028C-06ED-422D-866E-AE6C93075084.html#GUID-D581028C-06ED-422D-866E-AE6C93075084">Access
and manage information about landmarks</a> using the <a href="GUID-B8845FF1-D7F6-476A-8651-8B9C12D8789F.html#GUID-B8845FF1-D7F6-476A-8651-8B9C12D8789F">Landmarks
Service API</a></p></li>
<li><p><a href="GUID-CF55DBA3-2D4C-4FD0-8A06-862E6128F4E7.html#GUID-CF55DBA3-2D4C-4FD0-8A06-862E6128F4E7">Access
device logging events</a> using the <a href="GUID-F003B7DD-E450-49AD-B447-C5132FE47D3C.html#GUID-F003B7DD-E450-49AD-B447-C5132FE47D3C">Logging
Service API</a></p></li>
<li><p><a href="GUID-4DDE31C7-EC0D-4EEC-BC3A-A0B0351154F8.html#GUID-4DDE31C7-EC0D-4EEC-BC3A-A0B0351154F8">Access
device location information and perform location-based calculations</a> using
the <a href="GUID-53CE4DE6-F065-4339-8C18-5C30A9540053.html#GUID-53CE4DE6-F065-4339-8C18-5C30A9540053">Location Service
API</a></p></li>
<li><p><a href="GUID-E3D26890-581A-427F-8AFF-16081528A8B8.html#GUID-E3D26890-581A-427F-8AFF-16081528A8B8">Access
information about media files stored on a device</a> using the <a href="GUID-E5684FF0-28C9-4721-9421-6B9432087086.html#GUID-E5684FF0-28C9-4721-9421-6B9432087086">Media
Management Service API</a></p></li>
<li><p><a href="GUID-2240F5BE-97BD-4CB3-8DB3-B5CF7C23BF54.html#GUID-2240F5BE-97BD-4CB3-8DB3-B5CF7C23BF54">Send,
retrieve, and manage messages such as SMS and MMS</a> using the <a href="GUID-91579EE5-A608-401C-82B4-DCF1723EC7B5.html#GUID-91579EE5-A608-401C-82B4-DCF1723EC7B5">Messaging
Service API</a></p></li>
<li><p><a href="GUID-6FBE64B7-0949-4AAE-B835-52B276540A59.html#GUID-6FBE64B7-0949-4AAE-B835-52B276540A59">Access
data from the physical sensors of a device</a> using the <a href="GUID-B77C2006-879F-4AC6-B7BF-04B25B563A29.html#GUID-B77C2006-879F-4AC6-B7BF-04B25B563A29">Sensor
Service API</a></p></li>
<li><p><a href="GUID-E0ED671A-BBDA-4C07-828F-BD35782D9B36.html#GUID-E0ED671A-BBDA-4C07-828F-BD35782D9B36">Access
and modify system information on a device</a> using the <a href="GUID-AEB26A58-1DE2-46CB-81EC-6DB3A477B7A3.html#GUID-AEB26A58-1DE2-46CB-81EC-6DB3A477B7A3">SystemInfo
Service API<span> of WRT 1.1</span></a></p>
</li>
<li><p><a href="GUID-E9A578AA-58C5-4902-B418-4CE44EA40D5D.html#GUID-E9A578AA-58C5-4902-B418-4CE44EA40D5D">Access
system information and control certain device features</a> using the <a href="GUID-1A678A11-0BDD-4F64-9F40-013F6CDB81D7.html#GUID-1A678A11-0BDD-4F64-9F40-013F6CDB81D7">SystemInfo Service API of
WRT 1.0</a></p></li>
</ul>
<p/>
<p>The Service APIs are supported since <a href="GUID-1A3ECAC1-3F09-4602-A1CD-82164040A664.html#GUID-1A3ECAC1-3F09-4602-A1CD-82164040A664">WRT 1.1</a>.</p>
<div><h3>Using S60 Platform Services and Service
APIs</h3>
<p>Widgets use the S60 Platform Services through <a href="GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C.html#GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C">JavaScript
Service APIs</a> provided by the Web Runtime environment. Programming a
widget to access a service through its Service API involves two steps:</p>
<ol>
<li id="GUID-4BD63D17-33D3-4AC5-B04C-534DF27F5BFD"><a name="GUID-4BD63D17-33D3-4AC5-B04C-534DF27F5BFD"><!----></a><p>Create a service
object (an object for calling the Service API) using the <a href="GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080.html#GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080"><code>getServiceObject()</code></a> factory method provided by the <a href="GUID-571AF37F-1E95-462A-92D2-FEA2E62F1559.html#GUID-571AF37F-1E95-462A-92D2-FEA2E62F1559"><code>device</code></a> object.
This method uses a service provider name and an interface name to create the
appropriate service object:</p>
<pre class="codeblock" id="GUID-23173055-CA78-4B8B-ABD9-1C1DCD519C37">var so = device.getServiceObject(provider, interface);</pre>
<p>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.</p>
<p>For example, the service provider name for the <a href="GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4.html#GUID-CABB28B8-D2B1-496B-BD7E-34FF496E60B4">Calendar
Service API</a> is <code>Service.Calendar</code> and the supported
interface is <code>IDataSource</code>. To create a Calendar service
object, use the following code:</p>
<pre class="codeblock" id="GUID-7B715229-D37C-4009-B6F6-D4148E41F1B8">var so = device.getServiceObject("Service.Calendar", "IDataSource");</pre>
</li>
<li id="GUID-84C7D2C3-261C-47F5-8ABF-0B2196D3CC2D"><a name="GUID-84C7D2C3-261C-47F5-8ABF-0B2196D3CC2D"><!----></a><p>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.</p>
<p>For example, the <code>IDataSource</code> interface defines
the <code>GetList()</code> method, which returns an object as its
return value. To make a <code>GetList()</code> call with the Calendar
service object created above, use the following code:</p>
<pre class="codeblock" id="GUID-5E760EBA-FBEA-491A-985E-B015C372177C">var result = so.IDataSource.GetList(criteria);</pre>
</li>
</ol>
<p>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 <a href="GUID-1A678A11-0BDD-4F64-9F40-013F6CDB81D7.html#GUID-1A678A11-0BDD-4F64-9F40-013F6CDB81D7">JavaScript SystemInfo Service API (WRT 1.0)</a>.</p>
</div>
<div><h3>Arguments and return values</h3>
<p>Service API methods use <span>JavaScript</span> 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 <span>JavaScript</span> 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 <span><code>getNext()</code></span> method
on the iterator returns the next object in the ordered list.</p>
</div>
<div><h3>Creating objects in JavaScript</h3>
<p>In JavaScript, you can create an object in three ways.</p>
<p><strong>new() with dot notation syntax:</strong></p>
<pre class="codeblock" id="GUID-84B514EE-64A9-41C9-955B-55320F0C7D77">// 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;
</pre>
<p><strong>Object literal syntax:</strong></p>
<pre class="codeblock" id="GUID-91711FF3-169D-4D78-8FC8-A88D20147CB6">var criteria = { 'Type': 'FileInfo', 'Filter': { 'FileType': 'Sound' } };</pre>
<p><strong>new() with array syntax:</strong></p>
<pre class="codeblock" id="GUID-73B06F7A-D0F1-4573-BBC4-0362BEA4556B">// 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;
</pre>
</div>
</div></div></div><div class="footer"><hr/><div class="copy">© Nokia 2009.</div></div></body></html>