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

     2 **

     3 ** Copyright (C) 2009 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 #endif

    50 

    51 QTM_BEGIN_NAMESPACE

    52 

    53 /*!

    54     \class QGeoPositionInfoSource

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

    56     \ingroup location

    57 

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

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

    60     Otherwise, QGeoPositionInfoSource can be subclassed to create an appropriate

    61     custom source of position data.

    62 

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

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

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

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

    67     lastKnownPosition().

    68 

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

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

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

    72     For example:

    73 

    74     \code

    75         // Emit updates every 10 seconds if available

    76         QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource();

    77         source->setUpdateInterval(10000);

    78     \endcode

    79 

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

    81     setUpdateInterval() with a value of 0.

    82 

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

    84     update intervals, as returned by minimumUpdateInterval().

    85 

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

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

    88 */

    89 

    90 /*!

    91     \enum QGeoPositionInfoSource::PositioningMethod

    92     Defines the types of positioning methods.

    93 

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

    95     \value NonSatellitePositioningMethods Other positioning methods.

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

    97 */

    98 

    99 class QGeoPositionInfoSourcePrivate

   100 {

   101 public:

   102     int interval;

   103     QGeoPositionInfoSource::PositioningMethods methods;

   104 };

   105 

   106 

   107 /*!

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

   109 */

   110 

   111 QGeoPositionInfoSource::QGeoPositionInfoSource(QObject *parent)

   112         : QObject(parent),

   113         d(new QGeoPositionInfoSourcePrivate)

   114 {

   115     d->interval = 0;

   116     d->methods = 0;

   117 }

   118 

   119 /*!

   120     Destroys the position source.

   121 */

   122 QGeoPositionInfoSource::~QGeoPositionInfoSource()

   123 {

   124     delete d;

   125 }

   126 

   127 /*!

   128     \property QGeoPositionInfoSource::updateInterval

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

   130 

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

   132     source will provide updates as often as necessary.

   133 

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

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

   136     interval is less than the minimumUpdateInterval(),

   137     the minimum interval is used instead.

   138 

   139     The default value for this property is 0.

   140 

   141     Note: Subclass implementations must call the base implementation of

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

   143 */

   144 void QGeoPositionInfoSource::setUpdateInterval(int msec)

   145 {

   146     d->interval = msec;

   147 }

   148 

   149 int QGeoPositionInfoSource::updateInterval() const

   150 {

   151     return d->interval;

   152 }

   153 

   154 /*!

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

   156 

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

   158     unsupported method will be ignored.

   159 

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

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

   162 

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

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

   165 

   166     \sa supportedPositioningMethods()

   167 */

   168 void QGeoPositionInfoSource::setPreferredPositioningMethods(PositioningMethods methods)

   169 {

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

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

   172         d->methods = supportedPositioningMethods();

   173     }

   174 }

   175 

   176 /*!

   177     Returns the positioning methods set by setPreferredPositioningMethods().

   178 */

   179 QGeoPositionInfoSource::PositioningMethods QGeoPositionInfoSource::preferredPositioningMethods() const

   180 {

   181     return d->methods;

   182 }

   183 

   184 /*!

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

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

   187 

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

   189 */

   190 

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

   192 {

   193 #if defined(Q_OS_SYMBIAN)

   194     QGeoPositionInfoSource *ret = NULL;

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

   196     return ret;

   197 #elif defined(Q_OS_WINCE)

   198     return new QGeoPositionInfoSourceWinCE(parent);

   199 #elif defined(Q_WS_MAEMO_6)

   200     QGeoPositionInfoSourceMaemo *source = new QGeoPositionInfoSourceMaemo(parent);

   201 

   202     int status = source->init();

   203     if (status == -1) {

   204         delete source;

   205         return 0;

   206     }

   207 

   208     return source;

   209 #else

   210     Q_UNUSED(parent);

   211 #endif

   212     return 0;

   213 }

   214 

   215 /*!

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

   217 

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

   219     if none is available.

   220 

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

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

   223     is available, a null update is returned.

   224 */

   225 

   226 /*!

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

   228 

   229     Returns the positioning methods available to this source.

   230 

   231     \sa setPreferredPositioningMethods()

   232 */

   233 

   234 

   235 /*!

   236     \property QGeoPositionInfoSource::minimumUpdateInterval

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

   238 

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

   240     requestUpdate().

   241 */

   242 

   243 

   244 /*!

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

   246 

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

   248 

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

   250     as soon as they become available.

   251 

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

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

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

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

   256     periodic updates resume.

   257 */

   258 

   259 /*!

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

   261 

   262     Stops emitting updates at regular intervals.

   263 */

   264 

   265 /*!

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

   267 

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

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

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

   271     minimumUpdateInterval(), updateTimeout() is emitted.

   272 

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

   274     period as appropriate for the source.

   275 

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

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

   278     regular updates are in progress.

   279 

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

   281     current position from the most accurate positioning method within the

   282     given timeout.

   283 */

   284 

   285 /*!

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

   287 

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

   289     when an update becomes available.

   290 

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

   292 */

   293 

   294 /*!

   295     \fn void QGeoPositionInfoSource::updateTimeout();

   296 

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

   298     be retrieved within the specified timeout.

   299 

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

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

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

   303 */

   304 

   305 #include "moc_qgeopositioninfosource.cpp"

   306 

   307 QTM_END_NAMESPACE