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 "qgeopositioninfo.h"

    42 

    43 #include <QHash>

    44 #include <QDebug>

    45 #include <QDataStream>

    46 

    47 QTM_BEGIN_NAMESPACE

    48 

    49 class QGeoPositionInfoPrivate

    50 {

    51 public:

    52     QDateTime timestamp;

    53     QGeoCoordinate coord;

    54     QHash<int, qreal> doubleAttribs;

    55 };

    56 

    57 /*!

    58     \class QGeoPositionInfo

    59     \brief The QGeoPositionInfo class contains information gathered on a global position, direction and velocity at a particular point in time.

    60     \ingroup location

    61 

    62     A QGeoPositionInfo contains, at a minimum, a geographical coordinate and

    63     a timestamp. It may also have heading and speed measurements as well as

    64     estimates of the accuracy of the provided data.

    65 

    66     \sa QGeoPositionInfoSource

    67 */

    68 

    69 /*!

    70     \enum QGeoPositionInfo::Attribute

    71     Defines the attributes for positional information.

    72 

    73     \value Direction The bearing to true north from the direction of travel, in degrees.

    74     \value GroundSpeed The ground speed, in metres/sec.

    75     \value VerticalSpeed The vertical speed, in metres/sec.

    76     \value MagneticVariation The angle between the horizontal component of the magnetic field and true north, in degrees. Also known as magnetic declination. A positive value indicates a clockwise direction from true north and a negative value indicates a counter-clockwise direction.

    77     \value HorizontalAccuracy The accuracy of the provided latitude-longitude value, in metres.

    78     \value VerticalAccuracy The accuracy of the provided altitude value, in metres.

    79 */

    80 

    81 /*!

    82     Creates an invalid QGeoPositionInfo object.

    83 

    84     \sa isValid()

    85 */

    86 QGeoPositionInfo::QGeoPositionInfo()

    87         : d(new QGeoPositionInfoPrivate)

    88 {

    89 }

    90 

    91 /*!

    92     Creates a QGeoPositionInfo for the given \a coordinate and \a timestamp.

    93 */

    94 QGeoPositionInfo::QGeoPositionInfo(const QGeoCoordinate &coordinate, const QDateTime &timestamp)

    95         : d(new QGeoPositionInfoPrivate)

    96 {

    97     d->timestamp = timestamp;

    98     d->coord = coordinate;

    99 }

   100 

   101 /*!

   102     Creates a QGeoPositionInfo with the values of \a other.

   103 */

   104 QGeoPositionInfo::QGeoPositionInfo(const QGeoPositionInfo &other)

   105         : d(new QGeoPositionInfoPrivate)

   106 {

   107     operator=(other);

   108 }

   109 

   110 /*!

   111     Destroys a QGeoPositionInfo object.

   112 */

   113 QGeoPositionInfo::~QGeoPositionInfo()

   114 {

   115     delete d;

   116 }

   117 

   118 /*!

   119     Assigns the values from \a other to this QGeoPositionInfo.

   120 */

   121 QGeoPositionInfo &QGeoPositionInfo::operator=(const QGeoPositionInfo & other)

   122 {

   123     if (this == &other)

   124         return *this;

   125 

   126     d->timestamp = other.d->timestamp;

   127     d->coord = other.d->coord;

   128     d->doubleAttribs = other.d->doubleAttribs;

   129 

   130     return *this;

   131 }

   132 

   133 /*!

   134     Returns true if all of this object's values are the same as those of

   135     \a other.

   136 */

   137 bool QGeoPositionInfo::operator==(const QGeoPositionInfo &other) const

   138 {

   139     return d->timestamp == other.d->timestamp

   140            && d->coord == other.d->coord

   141            && d->doubleAttribs == other.d->doubleAttribs;

   142 }

   143 

   144 /*!

   145     \fn bool QGeoPositionInfo::operator!=(const QGeoPositionInfo &other) const

   146 

   147     Returns true if any of this object's values are not the same as those of

   148     \a other.

   149 */

   150 

   151 /*!

   152     Returns true if the timestamp() and coordinate() values are both valid.

   153 

   154     \sa QGeoCoordinate::isValid(), QDateTime::isValid()

   155 */

   156 bool QGeoPositionInfo::isValid() const

   157 {

   158     return d->timestamp.isValid() && d->coord.isValid();

   159 }

   160 

   161 /*!

   162     Sets the date and time at which this position was reported to \a timestamp.

   163 

   164     The \a timestamp must be in UTC time.

   165 

   166     \sa timestamp()

   167 */

   168 void QGeoPositionInfo::setTimestamp(const QDateTime &timestamp)

   169 {

   170     d->timestamp = timestamp;

   171 }

   172 

   173 /*!

   174     Returns the date and time at which this position was reported, in UTC time.

   175 

   176     Returns an invalid QDateTime if no date/time value has been set.

   177 

   178     \sa setTimestamp()

   179 */

   180 QDateTime QGeoPositionInfo::timestamp() const

   181 {

   182     return d->timestamp;

   183 }

   184 

   185 /*!

   186     Sets the coordinate for this position to \a coordinate.

   187 

   188     \sa coordinate()

   189 */

   190 void QGeoPositionInfo::setCoordinate(const QGeoCoordinate &coordinate)

   191 {

   192     d->coord = coordinate;

   193 }

   194 

   195 /*!

   196     Returns the coordinate for this position.

   197 

   198     Returns an invalid coordinate if no coordinate has been set.

   199 

   200     \sa setCoordinate()

   201 */

   202 QGeoCoordinate QGeoPositionInfo::coordinate() const

   203 {

   204     return d->coord;

   205 }

   206 

   207 /*!

   208     Sets the value for \a attribute to \a value.

   209 

   210     \sa attribute()

   211 */

   212 void QGeoPositionInfo::setAttribute(Attribute attribute, qreal value)

   213 {

   214     d->doubleAttribs[int(attribute)] = value;

   215 }

   216 

   217 /*!

   218     Returns the value of the specified \a attribute as a qreal value.

   219 

   220     Returns -1 if the value has not been set, although this may also

   221     be a legitimate value for some attributes.

   222     

   223     The function hasAttribute() should be used to determine whether or 

   224     not a value has been set for an attribute.

   225 

   226     \sa hasAttribute(), setAttribute()

   227 */

   228 qreal QGeoPositionInfo::attribute(Attribute attribute) const

   229 {

   230     if (d->doubleAttribs.contains(int(attribute)))

   231         return d->doubleAttribs[int(attribute)];

   232     return -1;

   233 }

   234 

   235 /*!

   236     Removes the specified \a attribute and its value.

   237 */

   238 void QGeoPositionInfo::removeAttribute(Attribute attribute)

   239 {

   240     d->doubleAttribs.remove(int(attribute));

   241 }

   242 

   243 /*!

   244     Returns true if the specified \a attribute is present for this

   245     QGeoPositionInfo object.

   246 */

   247 bool QGeoPositionInfo::hasAttribute(Attribute attribute) const

   248 {

   249     return d->doubleAttribs.contains(int(attribute));

   250 }

   251 

   252 #ifndef QT_NO_DEBUG_STREAM

   253 QDebug operator<<(QDebug dbg, const QGeoPositionInfo &info)

   254 {

   255     dbg.nospace() << "QGeoPositionInfo(" << info.d->timestamp;

   256     dbg.nospace() << ", ";

   257     dbg.nospace() << info.d->coord;

   258 

   259     QList<int> attribs = info.d->doubleAttribs.keys();

   260     for (int i = 0; i < attribs.count(); i++) {

   261         dbg.nospace() << ", ";

   262         switch (attribs[i]) {

   263             case QGeoPositionInfo::Direction:

   264                 dbg.nospace() << "Direction=";

   265                 break;

   266             case QGeoPositionInfo::GroundSpeed:

   267                 dbg.nospace() << "GroundSpeed=";

   268                 break;

   269             case QGeoPositionInfo::VerticalSpeed:

   270                 dbg.nospace() << "VerticalSpeed=";

   271                 break;

   272             case QGeoPositionInfo::MagneticVariation:

   273                 dbg.nospace() << "MagneticVariation=";

   274                 break;

   275             case QGeoPositionInfo::HorizontalAccuracy:

   276                 dbg.nospace() << "HorizontalAccuracy=";

   277                 break;

   278             case QGeoPositionInfo::VerticalAccuracy:

   279                 dbg.nospace() << "VerticalAccuracy=";

   280                 break;

   281         }

   282         dbg.nospace() << info.d->doubleAttribs[attribs[i]];

   283     }

   284     dbg.nospace() << ')';

   285     return dbg;

   286 }

   287 #endif

   288 

   289 #ifndef QT_NO_DATASTREAM

   290 /*!

   291     \fn QDataStream &operator<<(QDataStream &stream, const QGeoPositionInfo &info)

   292     \relates QGeoPositionInfo

   293 

   294     Writes the given \a info to the specified \a stream.

   295 

   296     \sa {Format of the QDataStream Operators}

   297 */

   298 

   299 QDataStream &operator<<(QDataStream &stream, const QGeoPositionInfo &info)

   300 {

   301     stream << info.d->timestamp;

   302     stream << info.d->coord;

   303     stream << info.d->doubleAttribs;

   304     return stream;

   305 }

   306 #endif

   307 

   308 #ifndef QT_NO_DATASTREAM

   309 /*!

   310     \fn QDataStream &operator>>(QDataStream &stream, QGeoPositionInfo &info)

   311     \relates QGeoPositionInfo

   312 

   313     Reads a coordinate from the specified \a stream into the given

   314     \a info.

   315 

   316     \sa {Format of the QDataStream Operators}

   317 */

   318 

   319 QDataStream &operator>>(QDataStream &stream, QGeoPositionInfo &info)

   320 {

   321     stream >> info.d->timestamp;

   322     stream >> info.d->coord;

   323     stream >> info.d->doubleAttribs;

   324     return stream;

   325 }

   326 #endif

   327 

   328 QTM_END_NAMESPACE