<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-8B4CC1A0-1A39-4AF0-826B-8DDB9A837A27" xml:lang="en"><title>Sensors
Framework Overview</title><shortdesc>The Sensors Framework consists of a sensor server and channel based
client APIs for supporting an extensible set of sensor hardware. The sensor
server defines a plug-in interface for adding sensor plug-ins for any type
of sensor hardware. The channel APIs enable client applications to interact
with the sensor hardware.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-10-1-9-1-1-6-1-4-1-3-1-3-1"><title>Key Concepts
and Terms</title><dl>
<dlentry>
<dt>Sensor Channel</dt>
<dd><p>The sensor channel forms a medium of interaction between the sensor
hardware and client applications. </p><p>The data from one physical sensor
can be mapped to several channels. For example, the Sensor System handling
an acceleration sensor can provide raw data on one channel and preprocessed
tap events on another.</p></dd>
</dlentry>
<dlentry>
<dt>Channel Properties</dt>
<dd><p>Channel properties contain properties of a specific channel, such as
data rate, availability, connection type and so on.</p></dd>
</dlentry>
<dlentry>
<dt>Data item</dt>
<dd><p>A data item is a discrete data package that contains sensor data or
an event parsed from sensor data and related values, such as timestamp. Each
channel provides a single type of data item only. </p></dd>
</dlentry>
<dlentry>
<dt>Channel condition</dt>
<dd><p> A value-operator pair targeting a single value inside a data item,
indicated by an index. A condition is met when the channel data value in comparison
with the condition value using condition operator is true. The conditions
are gathered in condition sets.</p><p>There are two condition types: single
limit conditions and range conditions. Range conditions are formed from two
separate conditions, representing the lower and upper limits of the range.</p></dd>
</dlentry>
<dlentry>
<dt>Channel Condition Set</dt>
<dd><p>A set of channel conditions. Following are the two types of condition
sets: <ul>
<li><p>AND condition set: An AND condition is met only if a data value satisfies
all conditions in the set.</p></li>
<li><p>OR condition: An OR condition is met if a data value satisfies even
one single condition in the set.</p></li>
</ul></p></dd>
</dlentry>
</dl>           </section>
<section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-10-1-9-1-1-6-1-4-1-3-1-3-2"><title>Description</title><p>The
sensor server provides a plug-in interface (Sensor Definitions APIs) that
enables platform developers to create sensor plug-ins for required sensors
hardware. The sensor plug-ins enable the interaction between a client application
and the sensor hardware through sensor channels. The Sensor Channel APIs provides
access to each sensor channel.</p><p>One physical sensor can
provide several different types of data.  For example, the physical magnetometer
can provide data for the Magnetometer channel and the Magnetic North channel.
Each sensor channel has its own sensor channel data definition in the Sensor
Definitions APIs that defines the format of the data package supplied by the
sensor channel. The data definition can also define properties for each data
item in the data package.</p><p>The sensor server facilitates the transfer
of data from one sensor hardware to multiple clients simultaneously. It also
resolves any contention between client applications for opening channels or
configuring a sensor device.</p>           </section>
<section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-10-1-9-1-1-6-1-4-1-3-1-3-3">       <title>APIs</title> 
     <table id="GUID-4D61C176-6A42-4F06-96A2-950F6ACD1C25">
<tgroup cols="2"><colspec colname="col1" colwidth="0.44*"/><colspec colname="col2" colwidth="1.56*"/>
<thead>
<row>
<entry>API</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>CSensrvChannelFinder</entry>
<entry>The channel finder provides functions to search and find sensor channels
that are supported by the Symbian device. </entry>
</row>
<row>
<entry>CSensrvChannel</entry>
<entry>The sensor channel provides functions to open and control a sensor
channel.</entry>
</row>
<row>
<entry>CSensrvChannelCondition</entry>
<entry>The sensor channel provides functions for notifying when a specific
condition is met.</entry>
</row>
<row>

<entry>CSensrvChannelConditionSet</entry>
<entry>The sensor channel condition set provides functions for adding one
or more channel conditions to a condition set.</entry>
</row>
<row>
<entry>MSensrvChannelListener</entry>
<entry>The sensor channel listener is a callback interface that tracks for
new channels installed on the Symbian device.</entry>
</row>
<row>
<entry>MSensrvChannelConditionListener</entry>
<entry>The sensor channel condition listener is a callback interface that
notifies the clients when a condition-set is satisfied.</entry>
</row>
<row>
<entry>MSensrvDataListener</entry>
<entry>The sensor data listener is a callback interface that notifies the
clients when the sensor data is available.</entry>
</row>
<row>
<entry>MSensrvPropertyListener</entry>
<entry>The sensor property listener is a callback interface that notifies
the client when a channel property changes.</entry>
</row>
</tbody>
</tgroup>
</table>  <fig id="GUID-90C26AB4-F003-444C-B9AF-422BB816557C">
<image href="GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e128297_href.png" placement="inline"/>
</fig><p>A physical sensor can supply data to several sensor channels (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCSensrvChannel.html" format="application/java-archive"><codeph>CSensrvChannel</codeph></xref>)
. A sensor channel provides data to an application in a channel-specific data
format (for example, <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/Sensor_definitions_APIClassesIndexPage.html" format="application/java-archive"><codeph>TSensrvXyzData</codeph></xref>) through a callback to the <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classMSensrvDataListener.html#7ddce5c72a9d429ddb9e69f9e3a0a9b6" format="application/java-archive"><codeph>MSensrvDataListener::DataReceived()</codeph></xref> interface. A
sensor channel has a single channel info item (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTSensrvChannelInfo.html" format="application/java-archive"><codeph>TSensrvChannelInfo</codeph></xref>) that describes the channel in general. A sensor channel has multiple
property items (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTSensrvProperty.html" format="application/java-archive"><codeph>TSensrvProperty</codeph></xref>)
that describe the channel in more detail. Each property item is referenced
by a property id and an index.</p>   </section>
<section id="GUID-7D9F56F7-0301-4FCF-8D88-1DDC6688E9CB"><title>Typical Uses</title><p>Using
the sensor channel APIs, you can perform the following operations:<ul>
<li><p>List all the sensor channels that are available for a particular sensor
type. For details, see <xref href="GUID-44FDDA27-1A5D-42B5-8DE0-D9E88EB75C93.dita">Querying
for Sensor Channels</xref></p></li>
<li><p>Receive and control periodic sensor data. </p>For details, see <xref href="GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita">Receiving Data from Sensors</xref></li>
<li><p>Configure sensor channels. </p> For details, see <xref href="GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita">Retrieving
Channel Properties</xref> and <xref href="GUID-0CA7F22E-59D7-4D65-9D6C-735E4E0F0454.dita">Setting
Channel Properties</xref></li>
<li><p>Receive notifications about sensor channel additions and removal. For
details, see <xref href="GUID-09E44FE5-6BEE-49FF-8BBF-CBB3C066EE10.dita">Receiving
Notifications about Channel Changes</xref></p></li>
<li><p>Configure a sensor channel to support conditional listening. This means
that you can configure it to notify you when the data on the channel matches
some particular values, or exceeds specified boundaries. For details, see <xref href="GUID-60EE22AA-402D-4FC2-9AD1-B3AEF822E8DC.dita">Receiving Channel Data based
on Conditions</xref>.</p></li>
</ul></p></section>
</conbody><related-links>
<link href="GUID-4B709839-8EEF-4AD2-9868-9AF0176B1E5B.dita"><linktext>Using Sensor
Channels APIs</linktext></link>
<link href="GUID-64AC6F53-A9A5-46FD-BCC6-4A9BD8D4DB5C.dita"><linktext>Compensating
Sensor Data for Display Orientation </linktext></link>
</related-links></concept>