Sending Location to a Remote Party - Overview

Purpose

This document describes the Transmit Location API, which allows client applications to send location data to remote parties.

Key concepts

Transmit position server

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.

Remote party

The remote destination to which the location is sent. This may be identified by a phone number, email address or web service URL.

Remote location server

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.

X3P request

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

API summary

The Transmit Location API consists of three classes:

• RLbsTransmitPositionServer

  Client applications use this class to create a session with the transmit position server.

• RLbsTransmitPosition

  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.

• TLbsTransmitPositionOptions 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.

Figure 1 shows the three classes.

To send location, an application must have the WriteDeviceData and NetworkServices capabilities.

The three classes of the Transmit Location API are defined in the file LbsX3P.h. Client applications link against Lbsx3p.lib.

Sending location data

Applications call RLbsTransmitPosition::TransmitPosition() to send location data to a remote location server. TransmitPosition() makes an asynchronous service request and calling applications pass a TRequestStatus parameter to be notified of completion.

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 LBS administration and LBS integration and configuration for more information about configuring LBS and quality profiles.

TransmitPosition()

There are two TransmitPosition() methods. To send the device location, an application calls one of them:

• void TransmitPosition(const TDesC& aDestinationID,TUint aTransmitPriority, TRequestStatus& aTransmittedPosStatus, TPositionInfo& aTransmittedPosInfo)

  This method takes four parameters:

  • aDestinationID is the phone number, email address or URL to which the device location is to be sent.

  • aTransmitPriority is the priority of the request.

  • aTransmittedPosStatus is a TRequestStatus variable from the calling object. This variable is used to notify when the location data is sent (or a failure or timeout occurs).

  • aTransmittedPosInfo is used to access the location data that is sent to the remote party.

  The calling application receives only one notification of completion (through aTransmittedPosStatus) when the calculated location is sent to the network (or there is a failure or timeout). An application calls this TransmitPosition() method when it requires only notification of the final state of its send location request.

• void TransmitPosition(const TDesC& aDestinationID,TUint aTransmitPriority, TRequestStatus& aRefPosStatus, TPositionInfo& aRefPosInfo, TRequestStatus& aTransmittedPosStatus, TPositionInfo& aTransmittedPosInfo)

  This method takes two additional parameters:

  • aRefPosStatus is a TRequestStatus variable from the calling object (it may be the same variable as aTransmittedPosStatus). This variable is used to notify when reference position data is obtained from the network (or a failure or timeout occurs).

  • aRefPosInfo is used to access the reference position data obtained from the network.

  The calling application receives two notifications. The first is an update of aRefPosStatus to notify the client application of receipt of reference position data from the network. The second notification is an update of aTransmittedPosStatus when the final calculated location is sent to the network.

TLbsTransmitPositionOptions

A client application can specify a timeout on its request to send location data by constructing a TLbsTransmitPositionOptions object and then calling RLbsTransmitPosition::SetTransmissionOptions() before calling RLbsTransmitPosition::TransmitPosition().

If no timeout is specified by calling SetTransmissionOptions() then a default timeout value is used. The default timeout is the value MaxTime specified in the quality profile for X3P requests. See LBS administration and LBS integration and configuration for more information about quality profiles.

Request priority

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.

A request's priority is set when RLbsTransmitPosition::TransmitPosition() is called (see above). The request priority is an unsigned integer number with priority zero as the highest priority. Higher numbers have decreasing priority.

Request cancellation

If a request is incomplete (location has not yet been sent to the network), it may be cancelled by calling RLbsTransmitPosition::CancelTransmitPosition(). Note however, that the location may still be sent to the network soon after CancelTransmitPosition() is called.

See also

How to send location to a remote party

LBS administration

LBS integration and configuration