Location Acquisition API: API description

The logical type of this API is Virtual Machine API and the technical type of this interface is client-server interface. The basis of Location Acquisition API is standard Symbian OS client-server implementation. The client application first connects to Location Server and then opens a sub-session through which the location information is obtained. It provides both asynchronous and synchronous methods, which should be taken into account to avoid unexpected blocking of the client application.

Use cases

The following are the main use cases for Location Acquisition API. They can be grouped in two ways:

Location acquisition related operations

• Obtaining current location estimate.
• Obtaining extended location information.
• Obtaining Last known location information.
• Cancelling the request for simple obtaining of a location estimate.
• Getting periodic location updates.
• Updating location with time-out.

Positioning Module related operations

• Getting positioning module information.
• Using specific positioning module for position information.
• Requesting notification on positioning module events

API class structure

Location Acquisition API contains a number of classes, which implement all the functionality of the interface. In the following sections, the classes are grouped according to their roles or according to the functionality they provide together.

Client-server communication classes

Figure 1 presents the class hierarchy and methods in both RPositionServer and RPositioner. These classes implement the client-server communication with Location Server. All requests from the client are sent through these classes. The figure also contains the main classes and methods for changing the behavior of position updates.

RPositionServer represents a session to Location Server. It is intended for establishing a connection with Location Server and for obtaining general positioning module information. It is the primary class for all client applications wishing to access Location Server. It can also be used to obtain details of which positioning technologies are available and of their current status.

RPositioner is used for requesting location information, controlling update behavior and managing privacy. The purpose of RPositioner is to create a second level connection (i.e. a sub-session) through which location information is passed from Location Server.

General position data classes

Figure 2 shows the class hierarchy, the member data and significant methods for the standard position and data retrieval classes. Some members are not presented in the figure for the sake of clarity.

TPositionInfo is the main position data holder. It contains TPosition, which encapsulates TLocality and TCoordinate information. This is the standard parameter type passed to RPositioner when a client application requests location information. It is a simple wrapper class used to hold the identifier of the positioning technology that produced the fix and a TPosition class that holds the location information itself.

HPositionGenericInfo allows storing of arbitrary data and it can also be used for client-server data transfer.

TPositionInfoBase is the base class for all position information classes, both standard and extended. It is the operand of location request calls.

The TPositionClassTypeBase class is used for determining the data class on Location Server.

The data classes TCoordinate, TLocality and TPosition provide certain utility methods. The following methods are provided by TCoordinate class:

1. Distance: This utility method calculates the distance between 2 locations. The distance is calculated using a value of 6,371,010 metres as an approximation of the Earth's radius. Altitude is not involved in the distance calculation.

   An error code, indicating error in the input arguments, is returned if there is information missing for the calculation.

2. BearingTo: This utility method calculates the bearing between source position to the target position without involving Altitude in the calculation. The bearing is also calculated using a value of 6,371,010 meters as an approximation of the Earth's radius.

   Error codes are returned for the following cases:

   • If there is information missing for the calculation , an error code indicating error in the input arguments is returned.
   • If the horizontal estimated accuracy circles of the two specified positions results in overlapping circles , the bearing and the bearing accuracy are not calculated. If the horizontal estimated accuracy circles of the two specified positions contain antipodal positions, the bearing and the bearing accuracy are not calculated. In this case return an error code, indicating that the value is not defined, instead of the bearing and the estimated bearing accuracy.
   • If the source position horizontal estimated accuracy circle includes one of the poles, the bearing and the bearing accuracy is not calculated. In this case, returns an error code, indicating that the value is not defined, instead of the bearing and the estimated bearing accuracy
3. Move: This utility method calculates a new location for a given TCoordinate object using bearing and distance information. The calculation does not take Altitude into consideration. The TCoordinate object's information is taken as the current location and calculations are based on that point.

The TPosition class adds the following utility method apart form those provided by TCoordinate class:

1. Speed: This method calculates the speed from two TPosition objects. Speed is also calculated without any involvement of Altitude information. The calculation is performed based on the timestamp and location information in the TPosition classes. If the source and target position time stamps are incorrect, the speed cannot be calculated, instead a return an error code, indicating that the value is not defined, is returned.

   The following time stamps are incorrect:

   • Either or both of the time stamps are zero.
   • The source and the target time stamps are equal.

Extended data retrieval classes

Figure 3 describes the hierarchy of the extended information retrieval classes provided by Location Acquisition API.

Extended data retrieval classes are used when specific location information is needed. The extended data retrieval classes are not required to be supported by every positioning module. The Location Acquisition API user can also define new extended data retrieval classes.

The TPositionCourseInfo class is used to get course information from a positioning module (if the module supports course information). It contains a TCourse class object, which represents the current speed of the device’s movement and the heading (direction) of the movement. It also provides information about the accuracy of these parameters.

TPositionSatelliteInfo gives physical information about the GPS network services used by the positioning device. This is a list of the visible and used GPS satellites, their properties and common satellite information. The satellites are described by TSatelliteData.

A client does not usually modify these classes. Instead, they are filled in by Location Server or the positioning module.

Module information, status and status event classes

Figure 4 presents the classes for holding information about a positioning module and the significant methods for manipulating the data. The diagram also shows the main classes and methods for obtaining module status information.

Module information may be important for the client because it influences the whole location retrieving process.

The TPositionModuleInfo class represents general information about a particular positioning module used by Location Server. In addition, the class contains a TPositionQuality class to describe the various parameters of the positioning module that influence location estimation. This information can be used by the client or Location Server when looking for an appropriate module for performing special tasks.

TPositionModuleStatus (and its parent class TPositionModuleStatusBase) gives access to the current state of a particular module. A client may register for notifications on module status changes. In this case, it receives information in the form of TPositionModuleStatusEvent (from the base class TPositionModuleStatusEventBase).

The TPositionQuality class defines quality parameters, which are also called Quality of Position (QoP) and are used for presenting positioning technology performance characteristics.

Privacy classes

Figure 5 depicts the main classes used to specify a chain of requestors.

The RRequestorStack class is used to transfer a list of the requestors participating in the current location requests to Location Server. Each item in the list is defined by a CRequestor definition of the requestor.

Update option classes

Figure 6 depicts the main classes used to control location request related options.

TPositionUpdateOptions is used by clients to define the behavior of position updates sent to them from Location Server. It is used as a parameter of RPositioner and RPositioner.