From 2caf8bb4546a0f87c2c60c19e87953a1aa7cfe35 Mon Sep 17 00:00:00 2001 From: Lincoln Ramsay Date: Wed, 5 Oct 2011 17:31:27 +1000 Subject: Update the front page. Link to topics in a more controlled manner. Change-Id: I6e3ec3d6c5920be66b628d954b470685764fdd33 Reviewed-on: http://codereview.qt-project.org/6024 Reviewed-by: Qt Sanity Bot Reviewed-by: Lincoln Ramsay --- doc/src/qtsensors-backend.qdoc | 218 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 doc/src/qtsensors-backend.qdoc (limited to 'doc/src/qtsensors-backend.qdoc') diff --git a/doc/src/qtsensors-backend.qdoc b/doc/src/qtsensors-backend.qdoc new file mode 100644 index 00000000..814cb5a6 --- /dev/null +++ b/doc/src/qtsensors-backend.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\group sensors_backend_topics +\title QtSensors Backend +\brief Information about the QtSensors back end + +The QtSensors backend connects the QtSensors API to the platform services or hardware sensors. + +\tableofcontents + +\section1 Overview + +\section1 Backend API + +QSensor instances talk to a backend object. Backends are usually supplied +with the QtSensors library for a specific device although third party +backends may be used as well. A backend may talk +directly to hardware or it may talk to a system service. In some instances +it may even talk to another sensor. +An example of this is the orientation sensor backend that talks to an +accelerometer to determine the device orientation. + +\section1 Backend Classes +If you are making sensors available through the Sensors API, these are the +classes to use. +\annotatedlist sensors_backend + +\section1 Backend Topics + +\generatelist related + +*/ + +/*! +\page creating-a-sensor-plugin.html +\title Creating a sensor plugin +\ingroup sensors_backend_topics + +\section1 How a sensor plugin is loaded + +Since sensor backends are created on demand, the sensor plugin is loaded and asked +to register the sensor backends it handles. The plugin should implement +QSensorPluginInterface::registerSensors() and call QSensorManager::registerBackend() +to register available backends. Typically the plugin will also inherit from +QSensorBackendFactory and implement +QSensorBackendFactory::createBackend() in order to instantiate backends it has registered. + +The simplest plugin will have just once sensor backend although there is no reason +that multiple sensor backends cannot be in a plugin. + +An example follows. + +\snippet snippets/sensors/plugin.cpp Plugin + +If you would like to build a backend into a library or application you can use the +REGISTER_STATIC_PLUGIN() macro although it may not work in all situations as it +uses static initialization. + +*/ + +/*! +\page determining-the-default-sensor-for-a-type.html +\title Determining the default sensor for a type +\ingroup sensors_backend_topics + +\section1 Multiple sensors can exist for a type + +Sensors was designed so that multiple sensors could exist for a given type. Why? +Consider this example. + +The N900 has an accelerometer built-in. It also features bluetooth and can pair +with a gaming controller that features an accelerometer. To a developer writing +a game these two devices are conceptually the same type. + +\section1 Default sensor for a type + +To avoid the need to know (or check) what the default sensor for a type is, the system will +use the default sensor for a type. Most of the time this is what the app developer wants to +do. In cases where the app developer wants to select a specific sensor they must call the +QSensor::setIdentifier() method before they start the sensor so that the appropriate backend +is used. + +From a system perspective though, selecting which sensor should be the default gets tricky. +The sensors library uses the first registered identifier as the default. This means that the +order in which sensor backends are registered is important so the system will allow a config +file to determine the default instead. + +\section1 Sensors.conf + +The config file that determines the default sensor for a type is called Sensors.conf. If present, +it is located in /etc/xdg/Nokia. It is read using QSettings so it has the standard formatting +of a QSettings .conf file. + +The settings live in the Default group and the general format is: +\code +type = identifier +\endcode + +An example Sensors.conf that ensures the N900 accelerometer is used as the default no matter the +order in which backends were registered is presented here. + +\code +[Default] +QAccelerometer = n900.accelerometer +\endcode + +If Sensors.conf specifies an identifier that is not registered then the system will fall back to +the first registered identifier as the default. + +Note that there is special case logic to prevent the generic plugin's backends from becoming the +default when another backend is registered for the same type. This logic means that a backend +identifier starting with \c{generic.} will only be the default if no other backends have been +registered for that type or if it is specified in \c{Sensors.conf}. + +*/ + +/*! +\page dynamic-sensor-backend-registration.html +\title Dynamic Sensor Backend Registration +\ingroup sensors_backend_topics + +\section1 Static Backend Registration + +Sensor backends are generally registered statically. The registration happens when the sensors +library is first used and the registration remains in effect while the program runs. + +\image sensors-static.png + +Statically registered backends may still exhibit some dynamic behaviour as the +QSensorBackendFactory is free to return 0 to indicate that a backend cannot be created. + +\section1 Dynamic Backend Registration + +While static registration is fine for most backends there are some situations where this is +problematic. + +The clearest example is backends that represent non-fixed hardware. As an example, lets consider +a game controller that is connected via Bluetooth. As there may be more than one game controller +in range of the phone, the program wants to record that a specific game controller should be used. +If the backend had been registered statically there would have been no unique information about +the controller. Instead, the registration is delayed until the controller is seen. + +\image sensors-dynamic.png + +\section1 Suggested Registration Policy + +A backend for fixed hardware should be registered immediately. Applications can see that the +sensor can be used. + +A backend for remote hardware should not be registered immediately. Applications can see that +the sensor cannot be used. When the remote hardware becomes available the backend should be +registered. Applications can see that the sensor is now available. + +If it is necessary to return 0 from a factory for a backend that was registered, the backend +should be unregistered. Applications can see that the sensor is no longer available. If the +factory can create the backend again it should be registered. Applications can see that the +sensor is available again. + +When the underlying hardware is no longer available, the backend should be deregistered. +Existing instances of the backend should report error states to the application but should +handle the situation gracefully. + +*/ + +/*! +\page meego-integration-notes.html +\title MeeGo Integration Notes +\ingroup sensors_backend_topics + +\section1 MeeGo Integration Notes + +The implementation of the API builds on top of the MeeGo Sensor Framework +that provides all the sensors specified in 1.2 API version. + +\section2 Available sensors + +If HW sensor is missing, the configuration file "Sensors.conf" +must be updated and sensor removed. The file +has the following format: + +\code +[Default] +QAccelerometer=meego.accelerometer +QAmbientLightSensor=meego.als +\endcode + +It lists sensor types and type's default implementation by giving the sensor id. +If the type is omitted then the backend does not support it in this device; this +gives a way of controlling and differentiating the supported sensor set. + +*/ + -- cgit v1.2.3