<?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>