1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt Mobility Components.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 #include <qgeopositioninfosource.h>

    42 

    43 #if defined(Q_OS_SYMBIAN)

    44 #   include "qgeopositioninfosource_s60_p.h"

    45 #elif defined(Q_OS_WINCE)

    46 #   include "qgeopositioninfosource_wince_p.h"

    47 #elif defined(Q_WS_MAEMO_6)

    48 #   include "qgeopositioninfosource_maemo_p.h"

    49 #elif defined(Q_WS_MAEMO_5)

    50 #   include "qgeopositioninfosource_maemo5_p.h"

    51 #endif

    52 

    53 QTM_BEGIN_NAMESPACE

    54 

    55 /*!

    56     \class QGeoPositionInfoSource

    57     \brief The QGeoPositionInfoSource class is an abstract base class for the distribution of positional updates.

    58     \ingroup location

    59 

    60     The static function QGeoPositionInfoSource::createDefaultSource() creates a default

    61     position source that is appropriate for the platform, if one is available.

    62     Otherwise, QGeoPositionInfoSource can be subclassed to create an appropriate

    63     custom source of position data.

    64 

    65     Users of a QGeoPositionInfoSource subclass can request the current position using

    66     requestUpdate(), or start and stop regular position updates using

    67     startUpdates() and stopUpdates(). When an update is available,

    68     positionUpdated() is emitted. The last known position can be accessed with

    69     lastKnownPosition().

    70 

    71     If regular position updates are required, setUpdateInterval() can be used

    72     to specify how often these updates should be emitted. If no interval is

    73     specified, updates are simply provided whenever they are available.

    74     For example:

    75 

    76     \code

    77         // Emit updates every 10 seconds if available

    78         QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(0);

    79         if (source)

    80             source->setUpdateInterval(10000);

    81     \endcode

    82 

    83     To remove an update interval that was previously set, call

    84     setUpdateInterval() with a value of 0.

    85 

    86     Note that the position source may have a minimum value requirement for

    87     update intervals, as returned by minimumUpdateInterval().

    88 

    89     \warning On Windows CE it is not possible to detect if a device is GPS enabled.

    90     The default position source on a Windows CE device without GPS support will never provide any position data.

    91 */

    92 

    93 /*!

    94     \enum QGeoPositionInfoSource::PositioningMethod

    95     Defines the types of positioning methods.

    96 

    97     \value SatellitePositioningMethods Satellite-based positioning methods such as GPS.

    98     \value NonSatellitePositioningMethods Other positioning methods.

    99     \value AllPositioningMethods A flag that matches all positioning methods.

   100 */

   101 

   102 class QGeoPositionInfoSourcePrivate

   103 {

   104 public:

   105     int interval;

   106     QGeoPositionInfoSource::PositioningMethods methods;

   107 };

   108 

   109 

   110 /*!

   111     Creates a position source with the specified \a parent.

   112 */

   113 

   114 QGeoPositionInfoSource::QGeoPositionInfoSource(QObject *parent)

   115         : QObject(parent),

   116         d(new QGeoPositionInfoSourcePrivate)

   117 {

   118     d->interval = 0;

   119     d->methods = 0;

   120 }

   121 

   122 /*!

   123     Destroys the position source.

   124 */

   125 QGeoPositionInfoSource::~QGeoPositionInfoSource()

   126 {

   127     delete d;

   128 }

   129 

   130 /*!

   131     \property QGeoPositionInfoSource::updateInterval

   132     \brief This property holds the requested interval in milliseconds between each update.

   133 

   134     If the update interval is not set (or is set to 0) the

   135     source will provide updates as often as necessary.

   136 

   137     If the update interval is set, the source will provide updates at an

   138     interval as close to the requested interval as possible. If the requested

   139     interval is less than the minimumUpdateInterval(),

   140     the minimum interval is used instead.

   141 

   142     Changes to the update interval will happen as soon as is practical, however the 

   143     time the change takes may vary between implementations.  Whether or not the elapsed 

   144     time from the previous interval is counted as part of the new interval is also 

   145     implementation dependent.

   146 

   147     The default value for this property is 0.

   148 

   149     Note: Subclass implementations must call the base implementation of

   150     setUpdateInterval() so that updateInterval() returns the correct value.

   151 */

   152 void QGeoPositionInfoSource::setUpdateInterval(int msec)

   153 {

   154     d->interval = msec;

   155 }

   156 

   157 int QGeoPositionInfoSource::updateInterval() const

   158 {

   159     return d->interval;

   160 }

   161 

   162 /*!

   163     Sets the preferred positioning methods for this source to \a methods.

   164 

   165     If \a methods includes a method that is not supported by the source, the

   166     unsupported method will be ignored.

   167 

   168     If \a methods does not include any methods supported by the source, the

   169     preferred methods will be set to the set of methods which the source supports.

   170 

   171     \bold {Note:} When reimplementing this method, subclasses must call the

   172     base method implementation to ensure preferredPositioningMethods() returns the correct value.

   173 

   174     \sa supportedPositioningMethods()

   175 */

   176 void QGeoPositionInfoSource::setPreferredPositioningMethods(PositioningMethods methods)

   177 {

   178     d->methods = methods & supportedPositioningMethods();

   179     if (d->methods == 0) {

   180         d->methods = supportedPositioningMethods();

   181     }

   182 }

   183 

   184 /*!

   185     Returns the positioning methods set by setPreferredPositioningMethods().

   186 */

   187 QGeoPositionInfoSource::PositioningMethods QGeoPositionInfoSource::preferredPositioningMethods() const

   188 {

   189     return d->methods;

   190 }

   191 

   192 /*!

   193     Creates and returns a position source with the given \a parent that

   194     reads from the system's default sources of location data.

   195 

   196     Returns 0 if the system has no default position source.

   197 */

   198 

   199 QGeoPositionInfoSource *QGeoPositionInfoSource::createDefaultSource(QObject *parent)

   200 {

   201 #if defined(Q_OS_SYMBIAN)

   202     QGeoPositionInfoSource *ret = NULL;

   203     TRAPD(error, ret = CQGeoPositionInfoSourceS60::NewL(parent));

   204     if (error != KErrNone)

   205         return 0;

   206     return ret;

   207 #elif defined(Q_OS_WINCE)

   208     return new QGeoPositionInfoSourceWinCE(parent);

   209 #elif (defined(Q_WS_MAEMO_6)) || (defined(Q_WS_MAEMO_5))

   210     QGeoPositionInfoSourceMaemo *source = new QGeoPositionInfoSourceMaemo(parent);

   211 

   212     int status = source->init();

   213     if (status == -1) {

   214         delete source;

   215         return 0;

   216     }

   217 

   218     return source;

   219 #else

   220     Q_UNUSED(parent);

   221     return 0;

   222 #endif

   223 }

   224 

   225 /*!

   226     \fn QGeoPositionInfo QGeoPositionInfoSource::lastKnownPosition(bool fromSatellitePositioningMethodsOnly = false) const = 0;

   227 

   228     Returns an update containing the last known position, or a null update

   229     if none is available.

   230 

   231     If \a fromSatellitePositioningMethodsOnly is true, this returns the last

   232     known position received from a satellite positioning method; if none

   233     is available, a null update is returned.

   234 */

   235 

   236 /*!

   237     \fn virtual PositioningMethods QGeoPositionInfoSource::supportedPositioningMethods() const = 0;

   238 

   239     Returns the positioning methods available to this source.

   240 

   241     \sa setPreferredPositioningMethods()

   242 */

   243 

   244 

   245 /*!

   246     \property QGeoPositionInfoSource::minimumUpdateInterval

   247     \brief This property holds the minimum time (in milliseconds) required to retrieve a position update.

   248 

   249     This is the minimum value accepted by setUpdateInterval() and

   250     requestUpdate().

   251 */

   252 

   253 

   254 /*!

   255     \fn virtual void QGeoPositionInfoSource::startUpdates() = 0;

   256 

   257     Starts emitting updates at regular intervals as specified by setUpdateInterval().

   258 

   259     If setUpdateInterval() has not been called, the source will emit updates

   260     as soon as they become available.

   261 

   262     An updateTimout() signal will be emitted if this QGeoPositionInfoSource subclass determines

   263     that it will not be able to provide regular updates.  This could happen if a satellite fix is

   264     lost or if a hardware error is detected.  Position updates will recommence if the data becomes

   265     available later on.  The updateTimout() signal will not be emitted again until after the

   266     periodic updates resume.

   267 */

   268 

   269 /*!

   270     \fn virtual void QGeoPositionInfoSource::stopUpdates() = 0;

   271 

   272     Stops emitting updates at regular intervals.

   273 */

   274 

   275 /*!

   276     \fn virtual void QGeoPositionInfoSource::requestUpdate(int timeout = 0);

   277 

   278     Attempts to get the current position and emit positionUpdated() with

   279     this information. If the current position cannot be found within the given \a timeout

   280     (in milliseconds) or if \a timeout is less than the value returned by

   281     minimumUpdateInterval(), updateTimeout() is emitted.

   282 

   283     If the timeout is zero, the timeout defaults to a reasonable timeout

   284     period as appropriate for the source.

   285 

   286     This does nothing if another update request is in progress. However

   287     it can be called even if startUpdates() has already been called and

   288     regular updates are in progress.

   289 

   290     If the source uses multiple positioning methods, it tries to gets the

   291     current position from the most accurate positioning method within the

   292     given timeout.

   293 */

   294 

   295 /*!

   296     \fn void QGeoPositionInfoSource::positionUpdated(const QGeoPositionInfo &update);

   297 

   298     If startUpdates() or requestUpdate() is called, this signal is emitted

   299     when an update becomes available.

   300 

   301     The \a update value holds the value of the new update.

   302 */

   303 

   304 /*!

   305     \fn void QGeoPositionInfoSource::updateTimeout();

   306 

   307     If requestUpdate() was called, this signal will be emitted if the current position could not

   308     be retrieved within the specified timeout.

   309 

   310     If startUpdates() has been called, this signal will be emitted if this QGeoPositionInfoSource

   311     subclass determines that it will not be able to provide further regular updates.  This signal

   312     will not be emitted again until after the regular updates resume.

   313 */

   314 

   315 #include "moc_qgeopositioninfosource.cpp"

   316 

   317 QTM_END_NAMESPACE