9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept xml:lang="en" id="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F"><title>How to Get Location Information</title><shortdesc>This document demonstrates how a client application uses the Location Acquisition API to get a position. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This tutorial explains how to get location information using the Location Acquisition API. </p> </section> <section><title>Required background</title> <p><xref href="GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita">Location Acquisition API Overview</xref> describes the main client/server classes of the API. </p> <p><xref href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita">Position Data and Info Classes</xref> describes the classes that hold location information. </p> </section> <section><title>Getting location information</title> <p>This section describes how to get location information using the Location Acquisition API. </p> <p><b>Introduction</b> </p> <p>Client applications use the <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> and <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> classes to get position updates. <codeph>RPositionServer</codeph> is used by client applications to manage a session with the Location Server and to get Positioning Module information. <codeph>RPositioner</codeph> is used by client applications to manage a subsession with the Location Server and to get position updates. </p> <p><b>GPS positioning modes</b> </p> <p>The Global Positioning System (GPS) is a technology that is often included in devices that support LBS. </p> <p>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. </p> <p>Each GPS positioning mode is a different way of getting a position fix: </p> <ul><li id="GUID-2BDDAACC-EB8D-5191-A42E-0BFA0B26C7DC"><p>Autonomous </p> <p>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. </p> </li> <li id="GUID-B2E24A6F-F46A-529E-A8F5-FC52F7CD8F0D"><p>Terminal Based Mode </p> <p>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. </p> <p>The network can also supply a <i>reference position</i> 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. </p> <p>See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API Runtime Behaviour</xref> for more information about the position updates that can be returned by LBS. </p> </li> <li id="GUID-018CA9E1-F191-5CC9-8DCD-8FE08CAABD28"><p>Terminal Assisted Mode </p> <p>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 <i>final network position</i>. The LBS subsystem returns this position to the client. </p> </li> <li id="GUID-9B1678F5-A53B-5245-9EE4-5809461E2EBB"><p>Simultaneous Terminal Based Mode and Terminal Assisted Mode. </p> <p>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. </p> </li> </ul> <p>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. </p> <p>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). </p> <p><b>Example sequence</b> </p> <p>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 <i>A-GPS Module</i> is a Positioning Module that uses Assisted GPS to calculate a position. The <i>Network Protocol Module</i> 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. </p> <fig id="GUID-FD5FEC83-B76D-5D45-AF40-DF5C2F17D404"><title> |
12 <concept xml:lang="en" id="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F"><title>How to Get Location Information</title><shortdesc>This document demonstrates how a client application uses the Location Acquisition API to get a position. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This tutorial explains how to get location information using the Location Acquisition API. </p> </section> <section><title>Required background</title> <p><xref href="GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita">Location Acquisition API Overview</xref> describes the main client/server classes of the API. </p> <p><xref href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita">Position Data and Info Classes</xref> describes the classes that hold location information. </p> </section> <section><title>Getting location information</title> <p>This section describes how to get location information using the Location Acquisition API. </p> <p><b>Introduction</b> </p> <p>Client applications use the <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> and <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> classes to get position updates. <codeph>RPositionServer</codeph> is used by client applications to manage a session with the Location Server and to get Positioning Module information. <codeph>RPositioner</codeph> is used by client applications to manage a subsession with the Location Server and to get position updates. </p> <p><b>GPS positioning modes</b> </p> <p>The Global Positioning System (GPS) is a technology that is often included in devices that support LBS. </p> <p>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. </p> <p>Each GPS positioning mode is a different way of getting a position fix: </p> <ul><li id="GUID-2BDDAACC-EB8D-5191-A42E-0BFA0B26C7DC"><p>Autonomous </p> <p>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. </p> </li> <li id="GUID-B2E24A6F-F46A-529E-A8F5-FC52F7CD8F0D"><p>Terminal Based Mode </p> <p>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. </p> <p>The network can also supply a <i>reference position</i> 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. </p> <p>See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API Runtime Behaviour</xref> for more information about the position updates that can be returned by LBS. </p> </li> <li id="GUID-018CA9E1-F191-5CC9-8DCD-8FE08CAABD28"><p>Terminal Assisted Mode </p> <p>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 <i>final network position</i>. The LBS subsystem returns this position to the client. </p> </li> <li id="GUID-9B1678F5-A53B-5245-9EE4-5809461E2EBB"><p>Simultaneous Terminal Based Mode and Terminal Assisted Mode. </p> <p>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. </p> </li> </ul> <p>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. </p> <p>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). </p> <p><b>Example sequence</b> </p> <p>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 <i>A-GPS Module</i> is a Positioning Module that uses Assisted GPS to calculate a position. The <i>Network Protocol Module</i> 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. </p> <fig id="GUID-FD5FEC83-B76D-5D45-AF40-DF5C2F17D404"><title> |
13 Figure 1. Simplified Terminal Based Mode Sequence |
13 Figure 1. Simplified Terminal Based Mode Sequence |
14 </title> <image href="GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e271226_href.png" placement="inline"/></fig> <p><b>Example code and description</b> </p> <p>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. </p> <codeblock id="GUID-7B350944-5178-586B-B381-87DC5104DD1F" xml:space="preserve">#include <lbs.h> |
14 </title> <image href="GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e267518_href.png" placement="inline"/></fig> <p><b>Example code and description</b> </p> <p>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. </p> <codeblock id="GUID-7B350944-5178-586B-B381-87DC5104DD1F" xml:space="preserve">#include <lbs.h> |
15 #include <lbserrors.h> |
15 #include <lbserrors.h> |
16 |
16 |
17 ... |
17 ... |
18 |
18 |
19 RPositionServer server; |
19 RPositionServer server; |
199 TPositionInfoBase::ETechnologyAssisted</codeph> </p> </li> <li id="GUID-289DE4DD-469D-58F0-8534-0B4353CDEC24"><p>Returned from the network, a position known as the <i>final network position</i> (for Terminal Assisted Mode) </p> <p>The value of <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita#GUID-D5B2E933-209D-3871-8E27-CC5C8855C745/GUID-A01CF36E-6EF9-395A-94DC-AB94478C66BE"><apiname>TPositionInfo::PositionMode()</apiname></xref> for a final network position depends on the configuration of the LBS subsystem: </p> <p>Normal behaviour is to return <codeph>TPositionInfo::PositionMode() |
199 TPositionInfoBase::ETechnologyAssisted</codeph> </p> </li> <li id="GUID-289DE4DD-469D-58F0-8534-0B4353CDEC24"><p>Returned from the network, a position known as the <i>final network position</i> (for Terminal Assisted Mode) </p> <p>The value of <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita#GUID-D5B2E933-209D-3871-8E27-CC5C8855C745/GUID-A01CF36E-6EF9-395A-94DC-AB94478C66BE"><apiname>TPositionInfo::PositionMode()</apiname></xref> for a final network position depends on the configuration of the LBS subsystem: </p> <p>Normal behaviour is to return <codeph>TPositionInfo::PositionMode() |
200 == TPositionModuleInfo::ETechnologyNetwork | |
200 == TPositionModuleInfo::ETechnologyNetwork | |
201 TPositionModuleInfo::ETechnologyAssisted</codeph>, but it is possible for LBS to return <codeph>TPositionModuleInfo::ETechnologyTerminal | |
201 TPositionModuleInfo::ETechnologyAssisted</codeph>, but it is possible for LBS to return <codeph>TPositionModuleInfo::ETechnologyTerminal | |
202 TPositionModuleInfo::ETechnologyAssisted</codeph> if it is configured to do so. See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information. </p> </li> </ul> <p>Note that <codeph>NotifyPositionUpdate()</codeph> may complete early if a GPS positioning module signals to LBS that it will be unable to return a location fix with the required quality criteria. In this case the Location Server returns the best location fix it can obtain to the client. The value of the <codeph>TRequestStatus</codeph> parameter of the client is set to either <codeph>KPositionQualityLoss</codeph> or <codeph>KErrNone</codeph> depending on the configuration of <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref>. </p> <p><b>Tracking </b> </p> <p>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. </p> <p>A client application has previously called <codeph>TPositionUpdateOptions::SetUpdateInterval(T)</codeph> and <codeph>RPositioner::SetUpdateOptions()</codeph> (not shown in figure 2). Partial updates are not set. LBS is also configured to return reference positions and accurate positions only (see <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information about this behaviour). The important points are: </p> <ul><li id="GUID-644F7437-0207-5B16-B38C-C695DC5BB83B"><p>A client application makes its first call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> (First NPUD in figure 2). </p> </li> <li id="GUID-E9F2BBA1-8F8A-516C-BB01-640535090820"><p>After a time t, the client's <codeph>RunL()</codeph> method is called and it receives its first position update (the reference position update Ref Pos in figure 2). This first position update is delivered to the client by LBS as soon as possible (t is as short as possible and is not equal to T). The client then makes its next call to <codeph>NotifyPositionUpdate()</codeph> (the next NPUD in figure 2). When tracking, a client application should make its next call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> as soon as possible in its <codeph>RunL()</codeph> method. The time between the client's <codeph>RunL()</codeph> and the client's next NPUD is exaggerated for clarity in Figure 2. </p> </li> <li id="GUID-8D670561-5F51-5836-AA24-3B0CC0417BB7"><p>At a time t + T (where T is the update interval) the client's <codeph>RunL()</codeph> method is called and it receives the next position update (GPS Pos in figure 2). The client makes its next call to <codeph>NotifyPositionUpdate()</codeph>. </p> </li> <li id="GUID-E93AE6CA-DF93-56AD-B68B-A60A1B96F128"><p>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). </p> </li> <li id="GUID-9E52BD1C-7BD4-55F8-BF75-98669883C0CF"><p>The client makes its next call to <codeph>NotifyPositionUpdate()</codeph> and at time t + (n+1)T the next position update is delivered (at t + 3T in figure 2). </p> <p> <i>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.</i> </p> </li> <li id="GUID-A7F59CB4-BFC7-5F88-8AF2-C8D6C24122D9"><p>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. </p> <p> </p> </li> </ul> <fig id="GUID-916FB3EF-08C6-5A0C-8D72-881FEEC7C161"><title> |
202 TPositionModuleInfo::ETechnologyAssisted</codeph> if it is configured to do so. See <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information. </p> </li> </ul> <p>Note that <codeph>NotifyPositionUpdate()</codeph> may complete early if a GPS positioning module signals to LBS that it will be unable to return a location fix with the required quality criteria. In this case the Location Server returns the best location fix it can obtain to the client. The value of the <codeph>TRequestStatus</codeph> parameter of the client is set to either <codeph>KPositionQualityLoss</codeph> or <codeph>KErrNone</codeph> depending on the configuration of <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref>. </p> <p><b>Tracking </b> </p> <p>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. </p> <p>A client application has previously called <codeph>TPositionUpdateOptions::SetUpdateInterval(T)</codeph> and <codeph>RPositioner::SetUpdateOptions()</codeph> (not shown in figure 2). Partial updates are not set. LBS is also configured to return reference positions and accurate positions only (see <xref href="GUID-4E56E531-5757-5740-9C7D-705D427FA9D5.dita">Location Acquisition API runtime behaviour</xref> for more information about this behaviour). The important points are: </p> <ul><li id="GUID-644F7437-0207-5B16-B38C-C695DC5BB83B"><p>A client application makes its first call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> (First NPUD in figure 2). </p> </li> <li id="GUID-E9F2BBA1-8F8A-516C-BB01-640535090820"><p>After a time t, the client's <codeph>RunL()</codeph> method is called and it receives its first position update (the reference position update Ref Pos in figure 2). This first position update is delivered to the client by LBS as soon as possible (t is as short as possible and is not equal to T). The client then makes its next call to <codeph>NotifyPositionUpdate()</codeph> (the next NPUD in figure 2). When tracking, a client application should make its next call to <codeph>RPositioner::NotifyPositionUpdate()</codeph> as soon as possible in its <codeph>RunL()</codeph> method. The time between the client's <codeph>RunL()</codeph> and the client's next NPUD is exaggerated for clarity in Figure 2. </p> </li> <li id="GUID-8D670561-5F51-5836-AA24-3B0CC0417BB7"><p>At a time t + T (where T is the update interval) the client's <codeph>RunL()</codeph> method is called and it receives the next position update (GPS Pos in figure 2). The client makes its next call to <codeph>NotifyPositionUpdate()</codeph>. </p> </li> <li id="GUID-E93AE6CA-DF93-56AD-B68B-A60A1B96F128"><p>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). </p> </li> <li id="GUID-9E52BD1C-7BD4-55F8-BF75-98669883C0CF"><p>The client makes its next call to <codeph>NotifyPositionUpdate()</codeph> and at time t + (n+1)T the next position update is delivered (at t + 3T in figure 2). </p> <p> <i>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.</i> </p> </li> <li id="GUID-A7F59CB4-BFC7-5F88-8AF2-C8D6C24122D9"><p>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. </p> <p> </p> </li> </ul> <fig id="GUID-916FB3EF-08C6-5A0C-8D72-881FEEC7C161"><title> |
203 Figure 2. Position updates when tracking |
203 Figure 2. Position updates when tracking |
204 </title> <image href="GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e272191_href.png" placement="inline"/></fig> <p><b>Error codes </b> </p> <p>The value of a client's <codeph>TRequestStatus</codeph> can be set to an LBS error code (defined in <filepath>lbserrors.h</filepath>) <i>or an error code defined in a licensee's Positioning Module</i>. An error causes <codeph>NotifyPositionUpdate()</codeph> to complete. An application should always check the value of <codeph>TRequestStatus</codeph> when its <codeph>RunL()</codeph> method is called. </p> <p><b>7. Cancel or complete a location information request </b> </p> <p>To cancel a location request a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-168130E7-459D-3108-9418-94773D802EAE"><apiname>RPositionerSubSessionBase::CancelRequest()</apiname></xref>, passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. The client's <codeph>TRequestStatus</codeph> is set to <codeph>KErrCancel</codeph> if the request was successfully cancelled and no position update is returned. </p> <p>To complete a location request early, a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-88F0FA62-BC72-3BC5-B42E-FA0A26F3E405"><apiname>RPositionerSubSessionBase::CompleteRequest()</apiname></xref> passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. Calling this method does not cancel the position update, but asks the Location Server to return any available position data. The returned position update may be different from that which would have been returned if the request had been allowed to complete normally. If the request is completed early, the client's <codeph>TRequestStatus</codeph> is set to <codeph>KPositionEarlyComplete</codeph>. </p> <p><b>8. Close the subsession and session </b> </p> <p> <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-DE09BADB-6D90-3995-A893-F949F9C37A2B"><apiname>RPositioner::Close()</apiname></xref> closes the subsession. <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-3D081F5B-F8D6-3168-951F-EDBC2364EB76"><apiname>RPositionServer::Close()</apiname></xref> closes the server session. In the code example the cleanup stack function is used. Any privacy requester objects created by a client must also be cleaned up. </p> </section> </conbody></concept> |
204 </title> <image href="GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e268483_href.png" placement="inline"/></fig> <p><b>Error codes </b> </p> <p>The value of a client's <codeph>TRequestStatus</codeph> can be set to an LBS error code (defined in <filepath>lbserrors.h</filepath>) <i>or an error code defined in a licensee's Positioning Module</i>. An error causes <codeph>NotifyPositionUpdate()</codeph> to complete. An application should always check the value of <codeph>TRequestStatus</codeph> when its <codeph>RunL()</codeph> method is called. </p> <p><b>7. Cancel or complete a location information request </b> </p> <p>To cancel a location request a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-168130E7-459D-3108-9418-94773D802EAE"><apiname>RPositionerSubSessionBase::CancelRequest()</apiname></xref>, passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. The client's <codeph>TRequestStatus</codeph> is set to <codeph>KErrCancel</codeph> if the request was successfully cancelled and no position update is returned. </p> <p>To complete a location request early, a client application calls <xref href="GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC.dita#GUID-BC95F637-51F6-3D99-9265-C6DFD903C5BC/GUID-88F0FA62-BC72-3BC5-B42E-FA0A26F3E405"><apiname>RPositionerSubSessionBase::CompleteRequest()</apiname></xref> passing a <xref href="GUID-355E1EEF-A312-3BB8-9655-9DD6805A3CDD.dita"><apiname>EPositionerNotifyPositionUpdate</apiname></xref> parameter. Calling this method does not cancel the position update, but asks the Location Server to return any available position data. The returned position update may be different from that which would have been returned if the request had been allowed to complete normally. If the request is completed early, the client's <codeph>TRequestStatus</codeph> is set to <codeph>KPositionEarlyComplete</codeph>. </p> <p><b>8. Close the subsession and session </b> </p> <p> <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-DE09BADB-6D90-3995-A893-F949F9C37A2B"><apiname>RPositioner::Close()</apiname></xref> closes the subsession. <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-3D081F5B-F8D6-3168-951F-EDBC2364EB76"><apiname>RPositionServer::Close()</apiname></xref> closes the server session. In the code example the cleanup stack function is used. Any privacy requester objects created by a client must also be cleaned up. </p> </section> </conbody></concept> |