6.6.1 GetList

GetList is used to retrieve the current location of the device.

The following are the examples for using GetList:

Synchronous

GetList_Output = location_handle.call('GetList', {'LocationInformationClass': u'BasicLocationInformation', 'Updateoptions': {'UpdateInterval':u'1', 'UpdateTimeOut': u'15', 'UpdateMaxAge' :u'0', 'PartialUpdates': u'False'}})

Asynchronous

event_id = location_handle.call('GetList', {'LocationInformationClass':  u'BasicLocationInformation', 'Updateoptions': {'UpdateInterval': u'1', 'UpdateTimeOut': u'15', 'UpdateMaxAge': u'0', 'PartialUpdates': u'False'}}, callback=get_list)

where, get_list is a user defined function.

The following table summarizes the specification of GetList:

Interface ILocation
Description Retrieves the current location of the device.
Response Model Synchronous and asynchronous
Pre-condition Device must be Location aware (that is, it must have some location information provider in form of GPS, AGPS, or Bluetooth).
ILocation interface loaded.
Post-condition Nil

Input Parameters

Input parameter specifies the category of location information and the update option used for retrieving location information.

Table 6.122: Input parameters for GetList
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

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

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

Table 6.123: Output parameters for GetList
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: GetList 6.124 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.



Table 6.124: map: GetList
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.


Errors

The following table lists the error codes and their values:

Table 6.125: Error codes
Error code value Description
-302 No Interface
0 Success
1007 No memory
1009 Server busy
1011 Access denied
1016 Service timed-out


Error Messages

The following table lists the error messages and their description:


Table 6.126: Error messages
Error messages Description
Location:GetList:Wrong category info should be BasicLocationInformation/ GenericLocationInfo Indicates argument supplied for category information is wrong.
Location:GetList:BadArgument - Updateoptions Indicates argument supplied for Updateoptions is wrong.
Location:GetList:Negative Time Interval Indicates time interval supplied is negative.
Location:GetList:Updateoptions Type Mismatch Indicates a wrongly supplied type for Updateoptions.


Example

The following sample code illustrates how to retrieve a list with location information, 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 get_list(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 landmarks are"
        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('GetList', {'LocationInformationClass': u'BasicLocationInformation', 'Updateoptions': {'UpdateInterval': u'1', 'UpdateTimeOut': u'15', 'UpdateMaxAge': u'0', 'PartialUpdates': u'False'}}, callback=get_list)

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

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