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-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>

    12 <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>

    13              Figure 1. Classes used to send location to a remote server 

    13              Figure 1. Classes used to send location to a remote server 

    15                 aTransmitPriority, TRequestStatus& aTransmittedPosStatus,

    15                 aTransmitPriority, TRequestStatus& aTransmittedPosStatus,

    16                 TPositionInfo&amp; 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&amp; aDestinationID,TUint

    16                 TPositionInfo&amp; 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&amp; aDestinationID,TUint

    17                 aTransmitPriority, TRequestStatus& aRefPosStatus, TPositionInfo&

    17                 aTransmitPriority, TRequestStatus& aRefPosStatus, TPositionInfo&

    18                 aRefPosInfo, TRequestStatus& aTransmittedPosStatus, TPositionInfo&

    18                 aRefPosInfo, TRequestStatus& aTransmittedPosStatus, TPositionInfo&

    19                 aTransmittedPosInfo)</codeph>  </p> <p>This method takes two additional parameters: </p> <ul><li id="GUID-D55C03B6-41B5-5603-B3B6-7449FAB12A3B"><p> <codeph>aRefPosStatus</codeph> is a <codeph>TRequestStatus</codeph> variable from the calling object (it may be the same variable as <codeph>aTransmittedPosStatus</codeph>). This variable is used to notify when reference position data is obtained from the network (or a failure or timeout occurs). </p> </li> <li id="GUID-2473DA51-241A-56A6-9C4F-7D4A31960DAC"><p> <codeph>aRefPosInfo</codeph> is used to access the reference position data obtained from the network. </p> </li> </ul> <p>The calling application receives two notifications. The first is an update of <codeph>aRefPosStatus</codeph> to notify the client application of receipt of reference position data from the network. The second notification is an update of <codeph>aTransmittedPosStatus</codeph> when the final calculated location is sent to the network. </p> </li> </ul> <p><b>TLbsTransmitPositionOptions </b> </p> <p>A client application can specify a timeout on its request to send location data by constructing a <xref href="GUID-FD409038-85FC-3442-9D8E-CBA80E9B5FD5.dita"><apiname>TLbsTransmitPositionOptions</apiname></xref> object and then calling <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-0100DFFE-E8AF-3ADB-AF86-F8EAD80B2B82"><apiname>RLbsTransmitPosition::SetTransmissionOptions()</apiname></xref> before calling <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>. </p> <p>If no timeout is specified by calling <codeph>SetTransmissionOptions()</codeph> then a default timeout value is used. The default timeout is the value <codeph>MaxTime</codeph> specified in the quality profile for 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 quality profiles. </p> <p><b>Request priority </b> </p> <p>The transmit position server can handle multiple requests from the same application or requests from different applications. Requests are queued and sent on a priority basis. If a new request is received that has a higher priority than any queued requests then the new request preempts the queued requests. </p> <p>A request's priority is set when <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> is called (see above). The request priority is an unsigned integer number with priority zero as the highest priority. Higher numbers have decreasing priority. </p> <p><b>Request cancellation </b> </p> <p>If a request is incomplete (location has not yet been sent to the network), it may be cancelled by calling <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-C7DC5CEC-A96C-3FBD-A0F5-FB986EC912DE"><apiname>RLbsTransmitPosition::CancelTransmitPosition()</apiname></xref>. Note however, that the location may still be sent to the network soon after <codeph>CancelTransmitPosition()</codeph> is called. </p> </section> <section><title>See also</title> <p><xref href="GUID-9711A7CD-8367-538C-9397-881FD0FE0703.dita">How to send location to a remote party</xref>  </p> <p><xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration</xref>  </p> <p><xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration</xref>  </p> </section> </conbody></concept>

    19                 aTransmittedPosInfo)</codeph>  </p> <p>This method takes two additional parameters: </p> <ul><li id="GUID-D55C03B6-41B5-5603-B3B6-7449FAB12A3B"><p> <codeph>aRefPosStatus</codeph> is a <codeph>TRequestStatus</codeph> variable from the calling object (it may be the same variable as <codeph>aTransmittedPosStatus</codeph>). This variable is used to notify when reference position data is obtained from the network (or a failure or timeout occurs). </p> </li> <li id="GUID-2473DA51-241A-56A6-9C4F-7D4A31960DAC"><p> <codeph>aRefPosInfo</codeph> is used to access the reference position data obtained from the network. </p> </li> </ul> <p>The calling application receives two notifications. The first is an update of <codeph>aRefPosStatus</codeph> to notify the client application of receipt of reference position data from the network. The second notification is an update of <codeph>aTransmittedPosStatus</codeph> when the final calculated location is sent to the network. </p> </li> </ul> <p><b>TLbsTransmitPositionOptions </b> </p> <p>A client application can specify a timeout on its request to send location data by constructing a <xref href="GUID-FD409038-85FC-3442-9D8E-CBA80E9B5FD5.dita"><apiname>TLbsTransmitPositionOptions</apiname></xref> object and then calling <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-0100DFFE-E8AF-3ADB-AF86-F8EAD80B2B82"><apiname>RLbsTransmitPosition::SetTransmissionOptions()</apiname></xref> before calling <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>. </p> <p>If no timeout is specified by calling <codeph>SetTransmissionOptions()</codeph> then a default timeout value is used. The default timeout is the value <codeph>MaxTime</codeph> specified in the quality profile for 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 quality profiles. </p> <p><b>Request priority </b> </p> <p>The transmit position server can handle multiple requests from the same application or requests from different applications. Requests are queued and sent on a priority basis. If a new request is received that has a higher priority than any queued requests then the new request preempts the queued requests. </p> <p>A request's priority is set when <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> is called (see above). The request priority is an unsigned integer number with priority zero as the highest priority. Higher numbers have decreasing priority. </p> <p><b>Request cancellation </b> </p> <p>If a request is incomplete (location has not yet been sent to the network), it may be cancelled by calling <xref href="GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF.dita#GUID-10A380F1-7550-336E-BAE4-8CB889C5BACF/GUID-C7DC5CEC-A96C-3FBD-A0F5-FB986EC912DE"><apiname>RLbsTransmitPosition::CancelTransmitPosition()</apiname></xref>. Note however, that the location may still be sent to the network soon after <codeph>CancelTransmitPosition()</codeph> is called. </p> </section> <section><title>See also</title> <p><xref href="GUID-9711A7CD-8367-538C-9397-881FD0FE0703.dita">How to send location to a remote party</xref>  </p> <p><xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS administration</xref>  </p> <p><xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS integration and configuration</xref>  </p> </section> </conbody></concept>