Add QSensor::isFeatureSupported()

Now it is possible to check if a backend supports a specific feature.
During reviews of features like acceleration mode or duplicate skipping,
the issue was raised how to check if these features are actually
supported. The same is true for existing features like
QMagnetometer::returnGeoValues.

Change-Id: I47115d6c487bbcbb668a9021cdc7085e6780a67c
Reviewed-by: Marc Mutz <marc.mutz@kdab.com>
Reviewed-by: Lorn Potter <lorn.potter@nokia.com>

7 files changed, 106 insertions, 0 deletions

diff --git a/src/imports/sensors/plugins.qmltypes b/src/imports/sensors/plugins.qmltypes
index fa5fd59..4828091 100644
--- a/src/imports/sensors/plugins.qmltypes
+++ b/src/imports/sensors/plugins.qmltypes
@@ -200,6 +200,15 @@ Module {
         prototype: "QObject"
         exports: ["Sensor 1.2", "Sensor 1.3"]
         exportMetaObjectRevisions: [0, 1]
+        Enum {
+            name: "Feature"
+            values: {
+                "Buffering": 0,
+                "AlwaysOn": 1,
+                "GeoValues": 2,
+                "FieldOfView": 3
+            }
+        }
         Property { name: "sensorid"; type: "QByteArray" }
         Property { name: "type"; type: "QByteArray"; isReadonly: true }
         Property { name: "connectedToBackend"; type: "bool"; isReadonly: true }
@@ -221,6 +230,11 @@ Module {
         Method { name: "start"; type: "bool" }
         Method { name: "stop" }
         Method { name: "connectToBackend"; type: "bool" }
+        Method {
+            name: "isFeatureSupported"
+            type: "bool"
+            Parameter { name: "feature"; type: "Feature" }
+        }
     }
     Component {
         name: "QSensorReading"
diff --git a/src/plugins/sensors/blackberry/bbsensorbackend.cpp b/src/plugins/sensors/blackberry/bbsensorbackend.cpp
index c13bc58..a1829b1 100644
--- a/src/plugins/sensors/blackberry/bbsensorbackend.cpp
+++ b/src/plugins/sensors/blackberry/bbsensorbackend.cpp
@@ -204,6 +204,20 @@ void BbSensorBackendBase::stop()
     m_deviceFile.close();
 }
 
+bool BbSensorBackendBase::isFeatureSupported(QSensor::Feature feature) const
+{
+    switch (feature) {
+    case QSensor:: AlwaysOn:
+        return true;
+    case QSensor::Buffering:
+    case QSensor::GeoValues:
+    case QSensor::FieldOfView:
+        break;
+    }
+
+    return false;
+}
+
 void BbSensorBackendBase::dataAvailable()
 {
     Q_FOREVER {
diff --git a/src/plugins/sensors/blackberry/bbsensorbackend.h b/src/plugins/sensors/blackberry/bbsensorbackend.h
index 5cfefbd..81c54bb 100644
--- a/src/plugins/sensors/blackberry/bbsensorbackend.h
+++ b/src/plugins/sensors/blackberry/bbsensorbackend.h
@@ -67,6 +67,7 @@ public:
 
     void start() Q_DECL_OVERRIDE;
     void stop() Q_DECL_OVERRIDE;
+    bool isFeatureSupported(QSensor::Feature feature) const Q_DECL_OVERRIDE;
 
 protected:
     QFile& deviceFile();
diff --git a/src/sensors/qsensor.cpp b/src/sensors/qsensor.cpp
index be0c786..9d41dbf 100644
--- a/src/sensors/qsensor.cpp
+++ b/src/sensors/qsensor.cpp
@@ -179,6 +179,33 @@ void QSensorPrivate::init(const QByteArray &sensorType)
 */
 
 /*!
+    \enum QSensor::Feature
+    \brief Lists optional features a backend might support.
+
+    The features common to all sensor types are:
+
+    \value Buffering The backend supports buffering of readings, controlled by the
+                     QSensor::bufferSize property.
+    \value AlwaysOn The backend supports changing the policy on whether to suspend when idle,
+                    controlled by the QSensor::alwaysOn property.
+
+    The features of QMagnetometer are:
+
+    \value GeoValues The backend supports returning geo values, which can be
+                     controlled with the QMagnetometer::returnGeoValues property.
+
+    The features of QLightSensor are:
+
+    \value FieldOfView The backend specifies its field of view, which can be
+                       read from the QLightSensor::fieldOfView property.
+
+    \omitvalue Reserved
+
+    \sa QSensor::isFeatureSupported()
+    \since 5.0
+*/
+
+/*!
     Construct the \a type sensor as a child of \a parent.
 */
 QSensor::QSensor(const QByteArray &type, QObject *parent)
@@ -471,6 +498,28 @@ void QSensor::setDataRate(int rate)
 }
 
 /*!
+   Checks if a specific feature is supported by the backend.
+
+   QtSensors supports a rich API for controlling and providing information about sensors. Naturally,
+   not all of this functionality can be supported by all of the backends.
+
+   To check if the current backend supports the feature \a feature, call this function.
+
+   The backend needs to be connected, otherwise false will be returned. Calling connectToBackend()
+   or start() will create a connection to the backend.
+
+   Backends have to implement QSensorBackend::isFeatureSupported() to make this work.
+
+   \return whether or not the feature is supported if the backend is connected, or false if the backend is not connected.
+   \since 5.0
+ */
+bool QSensor::isFeatureSupported(Feature feature) const
+{
+    Q_D(const QSensor);
+    return d->backend && d->backend->isFeatureSupported(feature);
+}
+
+/*!
     Start retrieving values from the sensor.
     Returns true if the sensor was started, false otherwise.
 
diff --git a/src/sensors/qsensor.h b/src/sensors/qsensor.h
index 8068926..43fe221 100644
--- a/src/sensors/qsensor.h
+++ b/src/sensors/qsensor.h
@@ -79,6 +79,7 @@ class Q_SENSORS_EXPORT QSensor : public QObject
     friend class QSensorBackend;
 
     Q_OBJECT
+    Q_ENUMS(Feature)
     Q_PROPERTY(QByteArray sensorid READ identifier WRITE setIdentifier)
     Q_PROPERTY(QByteArray type READ type)
     Q_PROPERTY(bool connectedToBackend READ isConnectedToBackend)
@@ -98,6 +99,14 @@ class Q_SENSORS_EXPORT QSensor : public QObject
     Q_PROPERTY(int bufferSize)
 #endif
 public:
+    enum Feature {
+        Buffering,
+        AlwaysOn,
+        GeoValues,
+        FieldOfView,
+        Reserved = 257 // Make sure at least 2 bytes are used for the enum to avoid breaking BC later
+    };
+
     explicit QSensor(const QByteArray &type, QObject *parent = 0);
     virtual ~QSensor();
 
@@ -142,6 +151,8 @@ public:
     static QList<QByteArray> sensorsForType(const QByteArray &type);
     static QByteArray defaultSensorForType(const QByteArray &type);
 
+    Q_INVOKABLE bool isFeatureSupported(Feature feature) const;
+
 public Q_SLOTS:
     // Start receiving values from the sensor
     bool start();
diff --git a/src/sensors/qsensorbackend.cpp b/src/sensors/qsensorbackend.cpp
index 7c65c59..d0a5b5c 100644
--- a/src/sensors/qsensorbackend.cpp
+++ b/src/sensors/qsensorbackend.cpp
@@ -72,6 +72,21 @@ QSensorBackend::~QSensorBackend()
 }
 
 /*!
+   Checks whether a feature is supported by this sensor backend.
+
+   This is the backend side of QSensor::isFeatureSupported(). Reimplement this function if the
+   backend supports one of the additional sensor features of QSensor::Feature.
+
+   \return whether the feature \a feature is supported by this backend. The default implementation returns false.
+   \since 5.0
+ */
+bool QSensorBackend::isFeatureSupported(QSensor::Feature feature) const
+{
+    Q_UNUSED(feature);
+    return false;
+}
+
+/*!
     Notify the QSensor class that a new reading is available.
 */
 void QSensorBackend::newReadingAvailable()
diff --git a/src/sensors/qsensorbackend.h b/src/sensors/qsensorbackend.h
index e14494f..824bfc1 100644
--- a/src/sensors/qsensorbackend.h
+++ b/src/sensors/qsensorbackend.h
@@ -60,6 +60,8 @@ public:
     virtual void start() = 0;
     virtual void stop() = 0;
 
+    virtual bool isFeatureSupported(QSensor::Feature feature) const;
+
     // used by the backend to set metadata properties
     void addDataRate(qreal min, qreal max);
     void setDataRates(const QSensor *otherSensor);