How to send location to a remote party

Purpose

This document explains how to send a mobile device's location to a remote party using the Transmit Location API.

Sending position to a remote party

To send location to a remote party, a client application:

• Creates a session with the transmit position server

• Sets a timeout period (if required)

• Makes a request on the transmit position server to send location data

• Receives notification of the request success, failure or timeout (notification of receipt of assistance data from the network may be received if required).

• Closes the server session

Applications that use the Transmit Location API include LbsX3P.h and link with Lbsx3p.lib and must have the Location and NetworkServices capabilities.

Creating a session and subsession

To create a session to send location data, a client application:

• Makes a connection to the transmit position server by calling RLbsTransmitPositionServer::Connect() to create a server session.

• Makes a subsession by calling RLbsTransmitPosition::Open(), passing the RLbsTransmitPositionServer reference as a parameter.

This is the standard procedure for using a Symbian server, shown in the code example below.

#include <lbsx3p.h>
#include <lbspositioninfo.h>

RLbsTransmitPositionServer server;
RLbsTransmitPosition transmitter;
    
User::LeaveIfError(server.Connect());
CleanupClosePushL(server);
    
User::LeaveIfError(transmitter.Open(server));
CleanupClosePushL(transmitter);

...

Setting a timeout period

A client application can set a timeout period if required. If the LBS subsystem is unable to send location data before the timeout, then the client request is cancelled.

The code fragment below sets a timeout of 5 seconds.

TLbsTransmitPositionOptions transmitPositionOptions(5000000);
transmitter.SetTransmitOptions(transmitPositionOptions);

...

Sending the location

An application must specify the destination to which the location is to be sent. The destination is specified when the location data is sent by calling RLbsTransmitPosition::TransmitPosition().

See Sending location to a remote party for more details about the two TransmitPosition() methods. In the code example below, the simplest method is used that notifies only when the final calculated location is sent to the network.

    
// Transmit location to remote party
    
TRequestStatus status;
TPositionInfo posInfo;
    
// Use an email address as the destination in this example
// A contact phone number could also be used

_LIT(destination, "someone@somewhere.com");
TInt priority = 0;
    
// Transmit location 
transmitter.TransmitPosition(destination, priority, status, posInfo);

// Simple example of waiting on this thread...
User::WaitForRequest(status);
    
if (status != KErrNone)
 {
 if (status == KErrTimedOut)
  {
  // Handle timeout...
  }
  else 
  {
  // Handle other possible errors...
  } 
 }

...

Cancelling a request

A request can be cancelled by calling RLbsTransmitPosition::CancelTransmitPosition(). When a request is cancelled, the TRequestStatus variable is set to KErrCancel. Note however, that the location may still be sent to the network soon after CancelTransmitPosition() is called.

Closing the server session

The server session should be closed when the application has finished sending location data to remote parties. The code example below uses the cleanup stack methods to do the cleanup.

CleanupStack::PopAndDestroy(&transmitter);
CleanupStack::PopAndDestroy(&server);

See also

Sending location to a remote party