TLbsLocation Class Reference

#include <lbslocation.h>

Inheritance diagram for TLbsLocation:
TLbsLocatorClassTypeBase

List of all members.

Public Member Functions

IMPORT_C TBool IsLatLongValid () const
IMPORT_C TReal64 Latitude () const
IMPORT_C TReal64 Longitude () const
IMPORT_C TReal32 Accuracy () const
IMPORT_C TBool IsAltitudeValid () const
IMPORT_C TReal32 Altitude () const
IMPORT_C TReal32 AltitudeAccuracy () const
IMPORT_C TBool IsSpeedValid () const
IMPORT_C TReal32 Speed () const
IMPORT_C TReal32 SpeedAccuracy () const
IMPORT_C TBool IsCourseValid () const
IMPORT_C TReal32 Course () const
IMPORT_C TReal32 CourseAccuracy () const
IMPORT_C TInt GetMeanSpeed (const TLbsLocation &aOtherLocation, TReal32 &aMeanSpeed) const
IMPORT_C TInt GetDistance (const TLbsLocation &aOtherLocation, TReal32 &aDistance) const
IMPORT_C TInt GetBearingTo (const TLbsLocation &aOtherLocation, TReal32 &aBearing) const
IMPORT_C TInt Move (TReal32 aBearing, TReal32 aDistance)
IMPORT_C TTime SystemTimeStamp () const
IMPORT_C TInt SetLocation (TReal64 aLatitude, TReal64 aLongitude, TReal32 aAccuracy)
IMPORT_C TInt SetAltitude (TReal32 aAltitude, TReal32 aAccuracy)
IMPORT_C TInt SetSpeed (TReal32 aSpeed, TReal32 aAccuracy)
IMPORT_C TInt SetCourse (TReal32 aCourse, TReal32 aAccuracy)
IMPORT_C TInt SetSystemTimeStamp (TTime aTimeStamp)

Detailed Description

TLbsLocation - Contains a position and its accuracy. May contain altitude, speed and course. See .cpp file for extended comments.


Member Function Documentation

EXPORT_C TReal32 TLbsLocation::Accuracy (  )  const

Retrieves the horizontal (circular) accuracy of the latitude and longitude in meters.

If the accuracy has not been assigned the method returns zero.

Applications should use IsLatLongValid() to determine if there is a valid accuracy.

Returns:
The circular accuracy in meters of the latitude and longitude
Zero if the location accuracy has not been assigned.
See also:
IsLatLongValid()
Latitude()
Longitude()
SetLocation()
EXPORT_C TReal32 TLbsLocation::Altitude (  )  const

Retrieves the altitude in meters for the location.

If the altitude is not available the method returns zero. Availability of altitude information is dependent on the underlying positioning technology and will not always be present.

Applications should use IsAltitudeValid() to determine if there is a valid altitude.

Returns:
The altitude in meters when the location contains a valid altitude.
Zero when altitude information is unavailable.
See also:
IsAltitudeValid()
AltitudeAccuracy()
SetAltitude()
EXPORT_C TReal32 TLbsLocation::AltitudeAccuracy (  )  const

Retrieves the vertical accuracy of the location.

If the altitude is not available the method returns zero. Availability of altitude information is dependent on the underlying positioning technology and will not always be present.

Applications should use IsAltitudeValid() to determine if there is a valid altitude.

Returns:
The vertical accuracy in meters when the location contains a valid altitide.
Zero when altitude information is unavailable.
See also:
IsAltitudeValid()
Altitude()
SetAltitude()
EXPORT_C TReal32 TLbsLocation::Course (  )  const

Retrieves the course in degrees counting clockwise relative to true north.

If the course is not available, the method returns zero.

Availability of course information is dependent on the underlying positioning technology and will not always be present. Even satellite based technologies may not provide course information in certain circumstances.

Applications should use IsCourseValid() to determine if there is a valid course.

When there is a valid course, the range of values will be from [0 to 360). That is: values can be up to (but will not include) 360. A value of 0 indicates the device is heading north.

Returns:
The course in degrees from the range [0 to 360) when the location contains a valid course.
Zero when course information is unavailable.
See also:
IsCourseValid()
CourseAccuracy()
SetCourse()
EXPORT_C TReal32 TLbsLocation::CourseAccuracy (  )  const

Retrieves the accuracy of the course information in degrees.

If the course is not available the method returns zero.

Availability of course information is dependent on the underlying positioning technology and will not always be present.

Applications should use IsCourseValid() to determine if there is a valid course.

When course information is available, the accuracy indicates the size of the error band. The actual course may be vary from the reported course but the difference should be less than or equal to the course accuracy.

Returns:
The accuracy of the course in degrees when the location contains a valid course.
Zero when course information is unavailable.
See also:
IsCourseValid()
Course()
SetCourse()
EXPORT_C TInt TLbsLocation::GetBearingTo ( const TLbsLocation aOtherLocation,
TReal32 &  aBearing 
) const

Calculate the bearing in degrees from this location to the supplied location.

Parameters:
[in] aOtherLocation Target location.
[out] aBearing Upon successful completion, this is set to the bearing from this location to aOtherLocation. Value is in degrees counting clockwise relative to true north.
Returns:
KErrNone When the bearing has been successfully calculated.
KErrArgument If any of the Latitudes or Longitudes have not been assigned.
KErrPositionIncalculable if this location is at a pole or if the two locations are the same or antipodal.
A Symbian OS error code if some other problem prevents the calculation.
EXPORT_C TInt TLbsLocation::GetDistance ( const TLbsLocation aOtherLocation,
TReal32 &  aDistance 
) const

Calculate the distance between this location and the supplied location.

Parameters:
[in] aOtherLocation A point different from this Location.
[out] aDistance Upon successful completion, this is set to the distance between this location and aOtherLocation, in meters.
Returns:
KErrNone When the distance has been successfully calculated.
KErrArgument If any of the Latitudes or Longitudes have not been assigned.
A Symbian OS error code if some other problem prevents the calculation.
EXPORT_C TInt TLbsLocation::GetMeanSpeed ( const TLbsLocation aOtherLocation,
TReal32 &  aMeanSpeed 
) const

This method calculates the mean horizontal speed in meters per second between this location and the supplied aOtherLocation. The speed is calculated based on the latitude and longitude of each of the locations and their system timestamps.

Parameters:
[in] aOtherLocation A point different from this Location.
[out] aMeanSpeed Upon successful completion, this is set to the speed indicated by being at this position at its recorded time, and at aOtherLocation at its recorded time. Always positive, in meters per second.
Returns:
KErrNone When the mean speed has been successfully calculated.
KErrArgument If any of the Latitudes, Longitudes, or System Timestamps have not been assigned.
KErrArgument If the System Timestamp for this or aOtherLocation are the same.
A Symbian OS error code if some other problem prevents the calculation.
EXPORT_C TBool TLbsLocation::IsAltitudeValid (  )  const

Determines if an altitude has been assigned.

Availability of altitude information is dependent on the underlying positioning technology and will not always be present.

Returns:
ETrue When a valid altitude is available for the location.
EFalse When altitude information is unavailable.
See also:
Altitude()
AltitudeAccuracy()
SetAltitude()
EXPORT_C TBool TLbsLocation::IsCourseValid (  )  const

Determines if a valid course is available.

Availability of course information is dependent on the underlying positioning technology and will not always be present. Even satellite based technologies may not provide course information in certain circumstances.

Returns:
ETrue When a valid course is available for the location.
EFalse When course information is unavailable.
See also:
Course()
CourseAccuracy()
SetCourse()
EXPORT_C TBool TLbsLocation::IsLatLongValid (  )  const

Determines if a latitude and longitude and (horizontal) accuracy has been assigned.

Positions returned by the location subsystem will have a valid latitude, longitude and accuracy.

When applications create their own instances of the TLbsLocation class this method will return EFalse until a latitude and longitude has been assigned.

Returns:
ETrue When a valid latitude and longitude are available for the location.
EFalse When no valid latitude and longitude are available for the location.
See also:
Latitude()
Longitude()
Accuracy()
SetLocation()
EXPORT_C TBool TLbsLocation::IsSpeedValid (  )  const

Determines if a valid speed is available.

Availability of speed information is dependent on the underlying positioning technology and will not always be present. Even satellite based technologies may not provide speed information in certain circumstances.

Returns:
ETrue When a valid speed is available for the location.
EFalse When speed information is unavailable.
See also:
Speed()
SpeedAccuracy()
SetSpeed()
EXPORT_C TReal64 TLbsLocation::Latitude (  )  const

Retrieves the latitude of the location. Coordinates are referenced to WGS84 datum.

If the latitude has not been assigned the method returns zero.

Applications should use IsLatLongValid() to determine if there is a valid latitude.

Returns:
The latitude of the location in degrees from the range -90 to +90 when the location contains a valid latitude.
Zero if the latitude has not been assigned.
See also:
IsLatLongValid()
Longitude()
Accuracy()
SetLocation()
EXPORT_C TReal64 TLbsLocation::Longitude (  )  const

Retrieves the longitude of the location. Coordinates are referenced to WGS84 datum.

If the longitude has not been assigned the method returns zero.

Applications should use IsLatLongValid() to determine if there is a valid longitude.

Returns:
The longitude of the location in degrees from the range 0 up to (but not including) 360 when the location contains a valid longitude.
Zero if the longitude has not been assigned.
See also:
IsLatLongValid()
Latitude()
Accuracy()
SetLocation()
EXPORT_C TInt TLbsLocation::Move ( TReal32  aBearing,
TReal32  aDistance 
)

This method moves this location aDistance in the direction specified by aBearing

Parameters:
[in] aBearing The direction to move this location. Value is in degrees counting clockwise relative to true north.
[in] aDistance The distance to move this Location. Value is in meters.
Returns:
KErrNone When the move has been successfully completed.
KErrArgument If the Latitude or Longitude for this location have not been assigned.
KErrPositionIncalculable if this location is at a pole.
A Symbian OS error code if some other problem prevents the calculation.
EXPORT_C TInt TLbsLocation::SetAltitude ( TReal32  aAltitude,
TReal32  aAccuracy 
)

Sets the altitude information for the location.

After the altitude has been successfully assigned, the method IsAltitudeValid will return ETrue.

Parameters:
[in] aAltitude The altitude of the location in meters.
[in] aAccuracy The accuracy of the course in degrees. Value cannot be negative
Returns:
KErrNone If parameter aAccuracy is in range and have been set successfully.
KErrArgument If parameter aAccuracy is negative.
See also:
IsAltitudeValid()
Altitude()
AltitudeAccuracy()
EXPORT_C TInt TLbsLocation::SetCourse ( TReal32  aCourse,
TReal32  aAccuracy 
)

Sets the course information for the location.

If the course paramater is outside the range [0,360) it will be automatically adjusted to fall within the valid range. For example, attempting to set a course 361 degrees will be converted to 1 degree.

After the course has been successfully assigned, the method IsCourseValid() will return ETrue.

Parameters:
[in] aCourse Degrees counting clockwise relative to true north. Normal range is 0 up to (but not including) 360.
[in] aAccuracy The accuracy of the course in degrees. Value cannot be negative
Returns:
KErrNone If parameter aAccuracy is in range and have been set successfully.
KErrArgument If parameter aAccuracy is negative.
See also:
IsCourseValid()
Course()
CourseAccuracy()
EXPORT_C TInt TLbsLocation::SetLocation ( TReal64  aLatitude,
TReal64  aLongitude,
TReal32  aAccuracy 
)

Sets the position information for the location.

If the latitude and longitude paramaters are outside the range [-90,+90], [0,360) the position will be automatically adjusted to fall within the valid range. For example, attempting to set a position of latitude 91, longitude 0 will be converted into 89, 180, respectively.

After these parameters have been successfully assigned, the method IsLatLongValid() will return ETrue.

Parameters:
[in] aLatitude The latitude of the location in degrees. Normal range is 0 up to (but not including) 360 degrees.
[in] aLongitude The longitude of the location in degrees. Normal range is -90 to +90 (inclusive).
[in] aAccuracy The accuracy of the course in degrees. Value cannot be negative
Returns:
KErrNone If parameter aAccuracy is in range and have been set successfully.
KErrArgument If parameter aAccuracy is negative.
See also:
IsLatLongValid()
Latitude()
Longitude()
Accuracy()
EXPORT_C TInt TLbsLocation::SetSpeed ( TReal32  aSpeed,
TReal32  aAccuracy 
)

Sets the speed information for the location.

After the speed has been successfully assigned, the method IsSpeedValid() will return ETrue.

Parameters:
[in] aSpeed The speed that is related to the location in meters per second. Value cannot be negative.
[in] aAccuracy The accuracy of the speed in meters per second. Value cannot be negative.
Returns:
KErrNone If all parameters are in range and have been set successfully.
KErrArgument If either parameter is negative.
See also:
IsSpeedValid()
Speed()
SpeedAccuracy()
EXPORT_C TInt TLbsLocation::SetSystemTimeStamp ( TTime  aTimeStamp  ) 

Sets the system time stamp for the location information.

This is the time when the location information entered the system.

The parameter aTimeStamp must contain a valid time and cannot be "zero".

Parameters:
[in] aTimeStamp The system time that is related to the location information.
Returns:
KErrNone If the time stamp has been set.
KErrArgument If the parameter is invalid. For example, a time stamp of zero was supplied.
See also:
SystemTimeStamp()
EXPORT_C TReal32 TLbsLocation::Speed (  )  const

Retrieves the speed in meters per second.

If the speed is not available the method returns zero.

Availability of speed information is dependent on the underlying positioning technology and will not always be present. Even satellite based technologies may not provide speed information in certain circumstances.

Applications should use IsSpeedValid() to determine if there is a valid speed.

Returns:
The speed in meters per second when the location contains a valid speed.
Zero when speed is unavailable.
See also:
IsSpeedValid()
SpeedAccuracy()
SetSpeed()
EXPORT_C TReal32 TLbsLocation::SpeedAccuracy (  )  const

Retrieves the accuracy of the speed information in meters per second.

If the speed is not available the method returns zero.

Availability of speed information is dependent on the underlying positioning technology and will not always be present.

When speed information is available, the accuracy indicates the size of the error band. The actual speed may be above or below the reported speed but the difference should be less than or equal to the speed accuracy.

Applications should use IsSpeedValid() to determine if there is a valid speed.

Returns:
The accuracy speed in meters per second when the location contains a valid speed.
Zero when the speed is unavailable.
See also:
IsSpeedValid()
Speed()
SetSpeed()
EXPORT_C TTime TLbsLocation::SystemTimeStamp (  )  const

Retrieves the time on the device when the location entered the system.

If this time stamp has not been assigned, a TTime of "zero" will be returned.

This timestamp is assigned by the local device and reflects when the location information injected. In particular, this timestamp does not provide technology specific information such as GPS time.

Returns:
The time when the location entered the system.
Zero If no valid course is available.
See also:
SetSystemTimeStamp()

The documentation for this class was generated from the following files:

Copyright (c) 2005-2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. These materials are provided under the terms of the Eclipse Public License v1.0.