org.symbian.tools.wrttools.doc.WebDeveloper/html/GUID-6FBE64B7-0949-4AAE-B835-52B276540A59.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="Accessing data from the physical sensors of a device"/><meta name="DC.Relation" scheme="URI" content="GUID-E0ED671A-BBDA-4C07-828F-BD35782D9B36"/><meta name="DC.Relation" scheme="URI" content="GUID-2240F5BE-97BD-4CB3-8DB3-B5CF7C23BF54"/><meta name="DC.Relation" scheme="URI" content="GUID-1EFD7043-E9B8-4B4E-9EA6-A20B3EECC14A"/><meta name="DC.Relation" scheme="URI" content="GUID-46EABDC1-37CB-412A-ACAD-1A1A9466BB68"/><meta name="DC.Format" content="XHTML"/><meta name="DC.Identifier" content="GUID-6FBE64B7-0949-4AAE-B835-52B276540A59"/><title>Accessing
data from the physical sensors of a device </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-6FBE64B7-0949-4AAE-B835-52B276540A59">Accessing
data from the physical sensors of a device</h1><div>
<p>The <a href="GUID-B77C2006-879F-4AC6-B7BF-04B25B563A29.html#GUID-B77C2006-879F-4AC6-B7BF-04B25B563A29">Sensor Service
API</a> allows <span>widgets</span> to access data provided by the
physical sensors of a device. The data from a given sensor is mapped to one
or more sensor channels, which the API can listen to. The available sensors
depend on the device. You can use the Sensor Service to create <span>widgets</span> that:</p>
<ul>
<li><p>Search for sensor channels available on a device</p></li>
<li><p>Listen for data provided by one or more sensor channels</p>
</li>
<li><p>Retrieve information about sensor channel properties</p>
</li>
</ul>
<p>Sensor information involves the following concepts:</p>
<ul>
<li><p><strong>Sensor</strong> is a physical sensor on a device (a piece of
hardware combined with a software plugin). A single sensor can provide multiple
sensor channels, such as a raw data channel and event channels, or incorporate
multiple sensor readings into a single sensor channel.</p></li>
<li><p><strong>Sensor property</strong> is a configuration value of a sensor.
The property affects all sensor channels that draw data from the sensor.</p>
</li>
<li><p><strong>Channel</strong> is an abstraction of a physical sensor. Data
from one physical sensor can be mapped to multiple sensor channels.</p>
</li>
<li><p><strong>Channel property</strong> is a configuration value of a sensor
channel. The property affects all clients listening to the channel.</p>
</li>
</ul>
<div><h3>Accessing the API and supported methods</h3>
<p>To create a <a href="GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080.html#GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080">service
object</a> for the Sensor Service API, use <code>Service.Sensor</code> to
identify the service provider and <code>ISensor</code> to identify
the supported interface:</p>
<pre class="codeblock" id="GUID-99272E68-27D3-4FBC-BB40-177578454568">var so = device.getServiceObject("Service.Sensor", "ISensor");</pre>
<p>The <code>ISensor</code> interface provides the following methods:</p>
<ul>
<li><p><a href="GUID-46DB749E-A388-46B2-BB13-A274385CA97C.html#GUID-46DB749E-A388-46B2-BB13-A274385CA97C"><code>FindSensorChannel()</code></a></p>
<p>Use the <code>FindSensorChannel()</code> method to search for
sensor channels available on the device.</p>
</li>
<li><p><a href="GUID-B4897257-F7BC-4C32-9C6C-A577FDAC5D09.html#GUID-B4897257-F7BC-4C32-9C6C-A577FDAC5D09"><code>RegisterForNotification()</code></a></p>
<p>Use the <code>RegisterForNotification()</code> method to receive
data from one sensor channel.</p>
</li>
<li><p><a href="GUID-3A306F4B-638D-4133-8575-2E269E565B7F.html#GUID-3A306F4B-638D-4133-8575-2E269E565B7F"><code>Cancel()</code></a></p>
<p>Use the <code>Cancel()</code> method to stop receiving data
provided by a <code>RegisterForNotification()</code> call.</p>
</li>
<li><p><a href="GUID-C2731B38-6294-419C-B7E2-AFB918F508D4.html#GUID-C2731B38-6294-419C-B7E2-AFB918F508D4"><code>GetChannelProperty()</code></a></p>
<p>Use the <code>GetChannelProperty()</code> method to retrieve
information about a sensor channel property.</p>
</li>
</ul>
</div>
<div><h3>Using the service in a widget</h3>
<p>To access sensor data on a device using the Sensor Service API:</p>
<ol>
<li id="GUID-E8ECDB2F-00C4-488F-A253-87FABDA66CA6-GENIDd0e8963"><a name="GUID-E8ECDB2F-00C4-488F-A253-87FABDA66CA6-GENIDd0e8963"><!----></a><p>Create a service
object for the API using <a href="GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080.html#GUID-04095E9A-50E7-4E5F-BD6F-71DA281A0080"><code>device.getServiceObject()</code></a>.</p>
</li>
<li id="GUID-0625B45D-A5C9-4ADA-BC21-07963F957A7C-GENIDd0e8972"><a name="GUID-0625B45D-A5C9-4ADA-BC21-07963F957A7C-GENIDd0e8972"><!----></a><p>Define the
tasks you want to perform and choose the correct methods for them.</p>
</li>
<li id="GUID-DBD9997B-CD51-45F9-9ED0-38A98AF08A12-GENIDd0e8977"><a name="GUID-DBD9997B-CD51-45F9-9ED0-38A98AF08A12-GENIDd0e8977"><!----></a><p>Optionally,
define how you want the results filtered.</p></li>
<li id="GUID-AAB5C193-F848-4B0A-AF03-6BA7425BD10B-GENIDd0e8981"><a name="GUID-AAB5C193-F848-4B0A-AF03-6BA7425BD10B-GENIDd0e8981"><!----></a><p>Define methods
to process the results.</p></li>
<li id="GUID-F0C3D20F-6F77-4C88-AF35-39DA70DE701B-GENIDd0e8985"><a name="GUID-F0C3D20F-6F77-4C88-AF35-39DA70DE701B-GENIDd0e8985"><!----></a><p>Retrieve the
results using the methods from step 2. Use asynchronous methods together with <a href="GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608.html#GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608"><code>callback()</code></a>.</p>
</li>
<li id="GUID-0ABE0CB0-D76C-444B-AE53-0D435B3C6E74-GENIDd0e8994"><a name="GUID-0ABE0CB0-D76C-444B-AE53-0D435B3C6E74-GENIDd0e8994"><!----></a><p>Process the
results using the methods defined in step 4.</p></li>
</ol>
<p>For the complete source of a sample widget that demonstrates how to
use this service, see <a href="GUID-350F3C29-923E-4C30-8B14-C3D594BB8E39.html#GUID-350F3C29-923E-4C30-8B14-C3D594BB8E39">the
full example</a>.</p>
</div>
</div></div></div><div class="footer"><hr/><div class="copy">© Nokia 2009.</div></div></body></html>