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.

The following is an example for using Trace:

event_id = location_handle.call('Trace', {'LocationInformationClass': u'GenericLocationInfo', 'Updateoptions': {'UpdateInterval': u'10', 'UpdateTimeOut': u'50', 'UpdateMaxAge': u'5', 'PartialUpdates': u'True'}}, callback=callback_function)

The following table summarizes the specification of Trace:

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

Input Parameters

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

Table 6.127: Input parameters for Trace
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
NA 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


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

Output Parameters

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

Table 6.128: Output parameters for Trace
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.

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.

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.

Table 6.129: map: Trace
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.


The following table lists the error codes and their values:

Table 6.130: Error codes
Error code value Description
0 Success
1011 Access denied
1012 Item not found

Error Messages

The following table lists the error messages and their description:

Table 6.131: Error messages
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"]
        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']


# 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!"
print "Request complete!"

See About this document... for information on suggesting changes.