6.6.2 Trace

Trace method is used to retrieve periodic updates on the current location of the device. You can use this method to track the movements of the device.

Input parameter specifies the type of device location information returned and how it is returned.

Name Type Range Description

[Location Information Class]

unicode string

Basic Location Information
Generic Location Info

This specifies category of location information. You will receive detailed location estimations on specifying Generic Location Info.

Default value for this argument is BasicLocationInformation.

Refer to Updateoptions description to know more about what are the output that are guaranteed to be in the location estimates for each of the LocationInformationClass provided.

[Updateoptions]

map
Name: Type
[UpdateInterval] (Microseconds): int32
[UpdateTimeOut] (Microseconds): int32
[UpdateMaxAge] (Microseconds): int32
[PartialUpdates] (Microseconds): bool

This specifies update option used while retrieving location estimation.

Default values are used if no argument is specified as part of input argument list.

UpdateInterval specifies the time interval between two consecutive location estimates.

If location server is not able to give location estimates within specified UpdateTimedOut, you will receive SErrTimedOut error.

UpdateMaxAge specifies the expiry time for the position information cache. It means that when a position request is made the position information can be returned from the cache, (Managed by location server) as long as the cache is not older that the specified maximum age.
The default value is zero that is, the position information will never be returned from cache.

Setting PartialUpdates to FALSE ensures that you will get at least BasicLocationInformation (Longitude, Latitude, and Altitude.)

By default, following values (in seconds) are used for these input parameters. UpdateInterval = 1
UpdateTimeOut = 15
UpdateMaxAge = 0
PartialUpdates = FALSE

note:

In case the following order is not maintained when you supply value for updateoption, it returns the error SErrArgument.
UpdateTimeOut>UpdateInterval>MaxAge

Output parameters contain the requested information. They also contain ErrorCode, and ErrorMessage if the operation fails.

Name	Type	Range (Type: string)	Description
`ErrorCode`	int	NA	Service specific error code on failure of the operation.
`ErrorMessage`	string	NA	Error description in Engineering English.
`ReturnValue`	For more information, refer table map: Trace 6.129	NA	It contains location estimations. In case you specify `BasicLocationInformation` in the input list only longitude, latitude and altitude will return. note: If `PartialUpdates` is set to FALSE you must get longitude, altitude and latitude. The WGS-84 datum is used to refer co-ordinates. Also representation is in decimal degree. In case generic information is requested, there is no guarantee that all information mentioned here will be obtained as it depends on the underlying GPS technology and other factor like number of satellites, which are available when location fix is obtained. note: Not all GPS technology are capable of retrieving all information listed here. For example, if you select network based positioning technology it does not have capability to retrieve satellites information. In situation where a particular field can not be retrieved from the underlying GPS technology, it will not be present in the output list mentioned here.

Data	Type	Description
`Longitude`	Double	This is the longitudinal data. Degree value is in the range [+180, -180].
`Latitude`	Double	This is the latitudinal data. Degree value is in the range [+90, -90].
`Altitude`	Double	Altitude data, height in meters.
`SatelliteNumView`	Double	Number of field satellite currently in view.
`SatelliteNumViewUsed`	Double	Number of satellites used.
`HorizontalSpeed`	Double	Horizontal speed, value in meters per second.
`HorizontalSpeedError`	Double	Horizontal speed error, value in meters per second.
`TrueCourse`	Double	This is the information about the current direction in degrees to true north.
`TrueCourseError`	Double	This is the true course error in degrees.
`MagneticHeading`	Double	This is the current direction in degrees to magnetic north.
`MagneticHeadingError`	Double	True magnetic course error in Degrees.
`Heading`	Double	This is the current instantaneous direction of travel in degrees to the true north.
`HeadingError`	Double	Heading error, value in degrees.
`MagneticCourse`	Double	This is the information about the current direction in degrees to magnetic north.
`MagneticCourseError`	Double	`Magneticcourser` error.

Error messages	Description
`Location:Trace:Invalid LocationInformationClass`	Indicates argument supplied for category information is wrong.
`Location:Trace:Updateoptions Type Mismatch`	Indicates wrong type for `Updateoptions`.
`Location:Trace:Badargument - updateoptions`	Indicates wrongly supplied `updateoptions`.
`Location:Trace:Negative Time Interval`	Indicates wrongly supplied time interval as part of `Updateoptions`.

The following sample code illustrates how to inform the consumer of any change in current location, in asynchronous mode:

import scriptext
import e32

# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()

# Callback function will be called when the requested service is complete
def Trace(trans_id, event_id, input_params):
    if event_id != scriptext.EventCompleted:   
# Check the event status
        print "Error in retrieving required info"
        print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
        if "ErrorMessage" in input_params["ReturnValue"]:
            print "Error message:" + input_params["ReturnValue"]["ErrorMessage"]
    else:
        print "The location change are as "
        for i in input_params["ReturnValue"]:
            print "Longitude"
            print i["Longitude"]
            print "Latitude"
            print i['Latitude']
            print "Altitude"
            print i['Altitude']
            print "SatelliteNumView"
            print i['SatelliteNumView']
            print "SatelliteNumViewUsed"
            print i['SatelliteNumViewUsed']
            print "HorizontalSpeed"
            print i['HorizontalSpeed']

    lock.signal()

# Async Query a location with search criteria
location_handle = scriptext.load('Service.Location', 'ILocation')
event_id = location_handle.call('Trace', {'LocationInformationClass': u'GenericLocationInfo', 'Updateoptions': {'UpdateInterval': u'10', 'UpdateTimeOut': u'50', 'UpdateMaxAge': u'5', 'PartialUpdates': u'True'}})

print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"

Interface	`ILocation`
Description	Tracks the movements of the device.
Response Model	Asynchronous
Pre-condition	Device must be Location aware (that is, it must have some location service provider in form of GPS, AGPS, or Bluetooth). ILocation interface loaded. No other instance of `Trace` is presently pending or is in use.
Post-condition	Nil