--- a/Symbian3/PDK/Source/GUID-33BACB23-5BEB-5A1A-85B2-71E6AA7730C4.dita Fri Jul 02 12:51:36 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-33BACB23-5BEB-5A1A-85B2-71E6AA7730C4.dita Fri Jul 16 17:23:46 2010 +0100
@@ -11,7 +11,7 @@
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-33BACB23-5BEB-5A1A-85B2-71E6AA7730C4"><title>Sending Location to a Remote Party - Overview</title><shortdesc>LBS allows a user to send their location to a remote party over a network. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This document describes the Transmit Location API, which allows client applications to send location data to remote parties. </p> </section> <section><title>Key concepts</title> <p><b>Transmit position server </b> </p> <p>The LBS Symbian server that sends position data to a remote location server in the network. Multiple applications can use the server simultaneously as transmit location requests are queued and prioritised. The Transmit Location API is the client application view of the transmit position server. </p> <p><b>Remote party </b> </p> <p>The remote destination to which the location is sent. This may be identified by a phone number, email address or web service URL. </p> <p><b>Remote location server </b> </p> <p>The network server that receives the location data sent from the handset. It is the first stage in routing the location data message to the destination remote party. </p> <p><b>X3P request </b> </p> <p>Transmit to third party request. The request made by a client application to calculate the mobile device location and to send it to a remote party (the 'third party'). More formally known as MO-LR (transfer to third party). </p> </section> <section><title>API summary</title> <p>The Transmit Location API consists of three classes: </p> <ul><li id="GUID-137412A2-F59F-5A0F-B7D2-23809955ED85"><p> <xref href="GUID-97CFE236-9DAD-3455-8969-6D0B4C484E0B.dita"><apiname>RLbsTransmitPositionServer</apiname></xref> </p> <p>Client applications use this class to create a session with the transmit position server. </p> </li> <li id="GUID-55711D51-FC49-58EF-9A07-95B930629F90"><p> <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita"><apiname>RLbsTransmitPosition</apiname></xref> </p> <p>Applications use this class to create a subsession with the transmit position server. Applications use the subsession to make requests to send location data to a remote location server. </p> </li> <li id="GUID-B23446D7-8396-56C3-8EA5-C0C9AAA17915"><p> <xref href="GUID-FD409038-85FC-3442-9D8E-CBA80E9B5FD5.dita"><apiname>TLbsTransmitPositionOptions</apiname></xref> is used to set a timeout on sending the location. If location data cannot be sent before the timeout expires then the send request is cancelled. </p> </li> </ul> <p>Figure 1 shows the three classes. </p> <fig id="GUID-656E1D67-CE50-5A82-8EB2-F9224033B718"><title>
Figure 1. Classes used to send location to a remote server
- </title> <image href="GUID-96FEE9E3-E870-5CE2-A049-9425B82894B0_d0e433894_href.png" placement="inline"/></fig> <p>To send location, an application must have the <codeph>WriteDeviceData</codeph> and <codeph>NetworkServices</codeph> capabilities. </p> <p>The three classes of the Transmit Location API are defined in the file <filepath>LbsX3P.h</filepath>. Client applications link against <filepath>Lbsx3p.lib</filepath>. </p> <p><b>Sending location data </b> </p> <p>Applications call <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-EB88EBE8-0B6A-359C-895C-15D063CAD4AA"><apiname>RLbsTransmitPosition::TransmitPosition()</apiname></xref> to send location data to a remote location server. <codeph>TransmitPosition()</codeph> makes an asynchronous service request and calling applications pass a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> parameter to be notified of completion. </p> <p>To calculate the device location, LBS may obtain position data from the network and/or from GPS hardware. The exact sequence of events is dependent upon which positioning modules are installed in the device and the quality profile that is configured for use with X3P requests. See <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration</xref> and <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration</xref> for more information about configuring LBS and quality profiles. </p> <p><b>TransmitPosition() </b> </p> <p>There are two <codeph>TransmitPosition()</codeph> methods. To send the device location, an application calls <i>one</i> of them: </p> <ul><li id="GUID-2CB2EA8F-C4E5-591C-A479-4C94A73856E3"><p> <codeph>void TransmitPosition(const TDesC& aDestinationID,TUint
+ </title> <image href="GUID-96FEE9E3-E870-5CE2-A049-9425B82894B0_d0e439739_href.png" placement="inline"/></fig> <p>To send location, an application must have the <codeph>WriteDeviceData</codeph> and <codeph>NetworkServices</codeph> capabilities. </p> <p>The three classes of the Transmit Location API are defined in the file <filepath>LbsX3P.h</filepath>. Client applications link against <filepath>Lbsx3p.lib</filepath>. </p> <p><b>Sending location data </b> </p> <p>Applications call <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-EB88EBE8-0B6A-359C-895C-15D063CAD4AA"><apiname>RLbsTransmitPosition::TransmitPosition()</apiname></xref> to send location data to a remote location server. <codeph>TransmitPosition()</codeph> makes an asynchronous service request and calling applications pass a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> parameter to be notified of completion. </p> <p>To calculate the device location, LBS may obtain position data from the network and/or from GPS hardware. The exact sequence of events is dependent upon which positioning modules are installed in the device and the quality profile that is configured for use with X3P requests. See <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration</xref> and <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration</xref> for more information about configuring LBS and quality profiles. </p> <p><b>TransmitPosition() </b> </p> <p>There are two <codeph>TransmitPosition()</codeph> methods. To send the device location, an application calls <i>one</i> of them: </p> <ul><li id="GUID-2CB2EA8F-C4E5-591C-A479-4C94A73856E3"><p> <codeph>void TransmitPosition(const TDesC& aDestinationID,TUint
aTransmitPriority, TRequestStatus& aTransmittedPosStatus,
TPositionInfo& aTransmittedPosInfo)</codeph> </p> <p>This method takes four parameters: </p> <ul><li id="GUID-C441043A-EF15-559A-BA2A-0CE8B7B28651"><p> <codeph>aDestinationID</codeph> is the phone number, email address or URL to which the device location is to be sent. </p> </li> <li id="GUID-AC7417D9-0432-5046-9112-737FCEB79575"><p> <codeph>aTransmitPriority</codeph> is the priority of the request. </p> </li> <li id="GUID-922173A5-6E60-544B-B8C7-B0869CA5F7D9"><p> <codeph>aTransmittedPosStatus</codeph> is a <codeph>TRequestStatus</codeph> variable from the calling object. This variable is used to notify when the location data is sent (or a failure or timeout occurs). </p> </li> <li id="GUID-1E268B8F-E710-5C7C-8D22-1E8C2C0812D3"><p> <codeph>aTransmittedPosInfo</codeph> is used to access the location data that is sent to the remote party. </p> </li> </ul> <p>The calling application receives only one notification of completion (through <codeph>aTransmittedPosStatus</codeph>) when the calculated location is sent to the network (or there is a failure or timeout). An application calls this <codeph>TransmitPosition()</codeph> method when it requires only notification of the final state of its send location request. </p> </li> <li id="GUID-1155FCDF-7C99-5B0C-A52A-144339889E13"><p> <codeph>void TransmitPosition(const TDesC& aDestinationID,TUint
aTransmitPriority, TRequestStatus& aRefPosStatus, TPositionInfo&