Sending Location to a Remote Party

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.

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

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