diff -r 80ef3a206772 -r 48780e181b38 Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita
--- a/Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita Tue Jul 20 12:00:49 2010 +0100
@@ -11,7 +11,7 @@
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
This tutorial explains how to get location information using the Location Acquisition API. This section describes how to get location information using the Location Acquisition API. Introduction Client applications use the GPS positioning modes The Global Positioning System (GPS) is a technology that is often included in devices that support LBS. For each location request from a client, the LBS subsystem can operate in one of several different GPS positioning modes. The Location Acquisition API hides the details of which GPS positioning mode is in use from client applications. A client makes the same sequence of calls to the API to get a position update whichever positioning mode is used. Note that only some of these positioning modes may be available to a client application at runtime. Each GPS positioning mode is a different way of getting a position fix: Autonomous LBS uses a GPS Positioning Module to calculate position fixes without assistance data from the network. This mode typically takes the longest time to obtain a location fix compared to the other modes. Terminal Based Mode LBS uses an A-GPS Positioning Module to calculate position fixes using assistance data from the network. Assistance data specifies the GPS satellites that are above the horizon as seen from the mobile device's current location. Assistance data is used by an A-GPS Positioning Module to reduce the time necessary to obtain a position fix. The network can also supply a reference position to the LBS subsystem as part of the sequence of events. This position is calculated in the network using cell-based techniques and may be less accurate than that obtained from GPS. If a reference position is available, it may be returned to the client before a GPS position. See Terminal Assisted Mode LBS uses an A-GPS Positioning Module to obtain GPS measurements (using assistance data from the network). GPS measurements are the raw data used to calculate a GPS fix. Measurements are sent to the network and a position fix is calculated by a remote server. The remotely calculated position fix is returned to the mobile device and is known as the final network position. The LBS subsystem returns this position to the client. Simultaneous Terminal Based Mode and Terminal Assisted Mode. LBS passes GPS measurements to the network (as in Terminal Assisted Mode), but also attempts to use those measurements to calculate a GPS position fix (as in Terminal Based Mode). The position returned to the client may be either a GPS position (calculated in the mobile device) or a final network position (calculated using the measurements by a remote server in the network). The position that is calculated first (the GPS position or the final network position) is generally returned to the client. The final network position may also be returned to the client after the return of the GPS position. Some devices also support a Cell-based Mode in which LBS obtains a position fix from the network without using GPS. This position fix is sometimes less accurate than that obtained using GPS. A client application cannot directly choose the GPS positioning mode that is used for its location request. A handset manufacturer may provide an LBS settings application where the GPS mode can be selected by an end user. However for modes that involve the network (Terminal Based Mode, Terminal Assisted Mode and Cell-based Mode) it is possible for a network operator to override the GPS mode as part of the location request. If a client wants to know precisely how a position fix was calculated, this information is available in the returned position info object (as described in more detail later in this document). Example sequence Figure 1 shows a simplified sequence for a client requesting a position update from LBS. The sequence shows simplified behaviour for Terminal Based Mode. The A-GPS Module is a Positioning Module that uses Assisted GPS to calculate a position. The Network Protocol Module is a Positioning Module that obtains GPS assistance data and reference positions (often approximate positions) from the network. Note that Terminal Based Mode may not be available on all mobile devices. This depends on the Positioning Modules that have been installed by the mobile device creator. Example code and description The following code shows a simple example of how a client application can get a single position update. The numbers in the code comments refer to sections that follow the code example. Example code and description The following code shows a simple example of how a client application can get a single position update. The numbers in the code comments refer to sections that follow the code example.
Note that
Tracking
A position update time line for tracking is shown in figure 2. Note that the exact behaviour of tracking on systems may differ from that shown in Figure 2.
A client application has previously called
A client application makes its first call to
After a time t, the client's
At a time t + T (where T is the update interval) the client's
The next position update is expected at time t + 2T, but in the case shown in figure 2 this is not possible (the mobile device may have moved into an area where the GPS signal is weak). In general if it is not possible to obtain an accurate GPS fix by time t + nT, but the fix is obtained a short time later, the next position update is delivered as soon as possible after time t + nT (after t + 2T in figure 2).
The client makes its next call to
The important point to note is that LBS attempts to deliver position updates at regular times t + nT but the time interval between position updates may temporarily be greater than or less than T.
Note that if partial updates were enabled, an incomplete position would be delivered at time t + 2T if it were available. Also note that an inaccurate position would be delivered if one was available at that time and LBS was configured to return it.
Error codes
The value of a client's
7. Cancel or complete a location information request
To cancel a location request a client application calls
To complete a location request early, a client application calls
8. Close the subsession and session
Error codes
The value of a client's
7. Cancel or complete a location information request
To cancel a location request a client application calls
To complete a location request early, a client application calls
8. Close the subsession and session