SlideShare ist ein Scribd-Unternehmen logo
1 von 44
Essential S60
Creating Location -
 Aware Applications
S60 essentials lbs_v1_0_en
Creating Location-Aware
Applications
part of the Essential S60 series
1st edition, 10/08

Published by:
Symbian Software Limited
2-6 Boundary Row
Southwark
London SE1 8HP
UK
www.symbian.com

Trademarks, copyright, disclaimer
‘Symbian’, ‘Symbian OS’ and other associated Symbian marks are all trademarks of Symbian
Software Ltd. Symbian acknowledges the trademark rights of all third parties referred to in this
material. Copyright © Symbian Software Ltd 2008. All rights reserved. No part of this material
may be reproduced without the express written permission of Symbian Software Ltd. Symbian
Software Ltd makes no warranty or guarantee about the suitability or the accuracy of the
information contained in this document. The information contained in this document is for
general information purposes only and should not be used or relied upon for any other
purpose whatsoever.

Compiled by:
Richard Bloor                                          Reviewed by:
Petro Soininen                                         Alexey Gusev
                                                       Husham Hamdan
Managing Editor:                                       Pekka Kosonen
Ashlee Godwin                                          Heikki Rasimaki
                                                       Jo Stichbury
                                                       Jure Sustersic
                                                       Lucian Tomuta
1

Contents
Introduction.................................................................................................................................2
Location-based services on mobile devices ...............................................................................3
A background to positioning technology....................................................................................4
   Satellite-based methods .........................................................................................................4
   Terrestrial-based methods .......................................................................................................5
   Mixed methods........................................................................................................................6
   Positioning methods supported by the S60 platform ............................................................6
Location services in the S60 platform ........................................................................................6
   Introducing the Mobile Location Framework...........................................................................7
   Working with location information..........................................................................................8
   Working with landmarks ........................................................................................................13
   Working with other features ..................................................................................................19
Other S60 platform runtimes ....................................................................................................20
   Java technology .....................................................................................................................20
   Web Runtime..........................................................................................................................21
   Flash Lite ...............................................................................................................................23
   Python for S60 ......................................................................................................................23
Building a complete application ...............................................................................................24
   Context options.....................................................................................................................24
   Sourcing context data ...........................................................................................................27
   Context data storage and access ..........................................................................................28
Development and testing tools ................................................................................................29
   Creating simulated location data ..........................................................................................29
   Using the positioning simulation tool for testing.................................................................30
Getting to market ......................................................................................................................31
   Independent channels ...........................................................................................................31
   Mobile network operators .....................................................................................................32
   System integrators ................................................................................................................32
   Device manufacturers ............................................................................................................32
Getting further assistance .........................................................................................................32
Conclusion.................................................................................................................................33
Developer resources..................................................................................................................34
   Community web sites ............................................................................................................34
2

Introduction
In an increasingly mobile world the desire to understand one’s surroundings and connect with
work colleagues, friends and family is growing among mobile device users. If the content of
your application relates to locations in the physical world, your users are going to expect the
application to be location-aware.

At the same time, an increasing proportion of S60 devices are shipping with integrated GPS.
This means that accurate information on a device’s location is often readily available. However,
even if a device does not include a GPS chip, many devices implement other methods of
obtaining location information.

To enable you to harness location information, S60 3rd Edition and S60 5th Edition (based on
Symbian OS v9.1 to v9.4) provide an easy to use set of APIs for Symbian C++, Java ME and
Python for S60. S60 5th Edition also offers you the ability to access location information in
Flash Lite from Adobe and Web Runtime (WRT). These APIs are built around a common Mobile
Location Framework (MLF).

This booklet provides information on:
   • the location-aware application market
   • location estimation technologies
   • the Symbian C++ location APIs
   • location APIs in other S60 platform runtimes
   • the factors to consider when making your application location-aware
   • development tools to assist with testing.

If you’re a developer looking to implement an LBS application for S60 devices, this Essential
S60 booklet is for you. While a significant portion of this booklet is dedicated to Symbian C++
coding, if you want to use another S60 runtime — such as Java ME, WRT or Flash Lite — you
will still find plenty of useful information throughout the booklet. In addition, specific coding
information for other runtimes is provided in the ‘Other S60 platform runtimes’ section. You
will also find more documentation on Forum Nokia’s web site (www.forum.nokia.com) about
the LBS services provided by your chosen runtime.

When you finish reading this booklet you will be ready to start making your applications for
the S60 platform location-aware.
3

Location-based services on mobile devices
The location-aware applications market is not new: enterprise and professional applications
have been around for many years. However, the availability of inexpensive, small, low-power
GPS chips and reliable network-based location technologies has moved the industry into a
growth phase (see Figure 1).




                      Figure 1: The location-aware application market is in a growth phase

Location-aware software covers a very broad range of applications, including:
   • navigation and route finding
   • location-based information, such as services providing information on points of interest
   • professional and enterprise, such as fleet management, vehicle dispatch, vehicle tracking
     and personnel tracking
   • community, such as friend locators and location-based sharing of pictures and
     information
   • entertainment, such as location-aware games
   • safety, such as child tracking, theft tracking and emergency location.

A survey conducted by CJ Driscoll and Associates (www.cjdriscoll.com) in 2006 found that of
the ten most desired non-voice applications for mobile devices, half were location-based. The
launch of the Nokia N95 multimedia computer, the first S60 device with an integrated GPS,
helped sales of location-aware applications from Nokia Software Market grow by over 500%
during 2007.1

So, mobile device users are clearly interested in and are willing to purchase location-aware
applications.



1 See www.symbianone.com/content/view/5119/31 for further information.
4

This opportunity has been recognized by many of the companies that offered mapping and
navigation services on dedicated GPS devices and as services to businesses. As a result there
is already a wealth of navigation and local discovery applications available for S60 devices. As
the market matures, S60 applications are appearing across many of the location-aware market
categories.

This does not, however, mean that the opportunities for new location-based S60 applications
are limited. The first wave of location-based applications largely involved transplanting existing
functionality into an S60 application. The second wave will combine location information with
other information in unique and innovative ways to truly take advantage of the capabilities of
mobile devices and fulfil the needs of mobile device users. These opportunities exist as
strongly in the consumer market as they do in business applications.

Consider the following possibilities:
  • An events calendar that allows users to find events by date and proximity, then provides
     navigation information to assist travel to an event.
  • A car park finder application that allows the user to identify suitable car parking at a
     location they are driving to, reserves a parking space and then provides directions to the
     car park.
  • An application that allows users to find the best price for a product based on the purchase
     cost and the cost of travel to the shop. The user could look for several products and the
     application could find the best route to balance travel costs with purchase prices.
  • A personal management application that could keep track of the user’s travel between
     diary events and automatically alert meeting attendees of a delay if traffic congestion is
     holding up the user.

Hopefully these examples will have fired your imagination to recognize that there are still many
possibilities for location-based applications and games, and many ways in which existing
applications could benefit from location-awareness.


A background to positioning technology
The essential information a location-aware application needs is, rather obviously, information
on location. There are several methods available for determining location and two basic
technologies: satellite-based and terrestrial radio, as well as hybrid approaches that combine
the best features of these two basic technologies. Each has its advantages and disadvantages,
which we will review now.

Satellite-based methods
These methods rely on using information supplied by a network of medium earth orbit
satellites. At the time of writing, this effectively means NAVSTAR-GPS, created by the United
States Department of Defense, but which is generally referred to as the Global Positioning
System (GPS). Other systems are in the process of being constructed or planned, such as the
Russian GLONASS and the European Galileo positioning systems.

In simplistic terms, a GPS receiver estimates its location by determining its distance from at
least four GPS satellites. These distances are found using information on when a signal was
transmitted by a satellite and its location at that time. Knowing these distances, the GPS
receiver’s software can determine its location.
5

The advantages of GPS-based location determination are that:
   • it is free (once the necessary hardware has been obtained)
   • it does not rely on the device being connected to a radio network
   • it is very accurate where signals from the satellites can be received (typically within tens
     of meters for consumer GPS receivers).

The principal disadvantages of GPS are that:
   • it requires dedicated hardware
   • it may not work in all locations. GPS receivers cannot be used to determine location
     indoors, in built-up areas with a high density of tall buildings, or in some natural
     locations such as canyons or steep sided valleys
   • GPS systems do not necessarily provide an instant response, requiring time to locate
     satellite signals when first requested for a location
   • integrated GPS hardware can have an appreciable effect on a device’s power
     consumption. This may need to be considered during the design of applications where
     prolonged use of an internal GPS receiver is likely.

Terrestrial-based methods
These methods rely on information a device can gather about terrestrial-radio networks. For
mobile devices this means mobile network base stations, but WiFi and Bluetooth technology
hotspots could also be used. If a device can determine the source of any radio signals and
their strength then an estimate of location can be made, but only if the location of the source
is already recorded.

The advantages of terrestrial radio-based methods are that:
   • they do not rely on specific GPS location hardware and so can be used by any mobile
     device
   • these methods can often be the most accurate for determining location in built up areas.
     In these areas satellite systems may be ineffective because buildings obscure their
     signals, while terrestrial radio methods benefit from a high density of mobile network
     base stations, which can be supplemented with information from the often numerous
     WLAN networks.

The disadvantages of these methods are that:
   • their accuracy can be low. Where there are a limited number of radio sources available,
     accuracy may be measured in kilometers
   • they are unable to provide altitude information
   • terrestrial radio-based methods rely on the availability of information on the location of
     radio sources and, where possible, information on the signal strength footprint or the use
     of techniques for determining the time a signal takes to arrive. As a result, these
     methods rely on either a database stored on the device, one accessed over-the-air or a
     combined method that caches relevant information on the device. A fixed on-device
     database will become less relevant over time, while use of an external database could
     result in the device user paying network charges to access it.
6

Mixed methods
Mixed location technologies attempt to take advantage of the best characteristics of terrestrial
radio and satellite-based positioning methods to improve the accuracy, time-to-first-fix or
availability of positioning information.

Several different mixed method technologies are available, including Assisted GPS System (A-
GPS) and Differential Global Positioning System (DGPS). Their operation is generally similar,
using the best available information to determine location, for example, an A-GPS system may
use Secure User Plane Location (SUPL) (an Open Mobile Alliance [OMA] standard for
transferring location information) to estimate a location based on information from the cellular
network. This enables improved time-to-first-fix (when a location request is first made and a
GPS is searching for satellites or when the signals available to the GPS are weak or
incomplete).

Positioning methods supported by the S60 platform
At the time of writing, the S60 platform supports all three methods of location determination
in the following forms:
    • external Bluetooth GPS
    • built-in GPS
    • A-GPS (using a built-in GPS)
    • network (terrestrial radio)-based triangulation.

In addition, a method of simulating location is also supported for testing purposes; this
method is discussed later in the ‘Development and testing tools’ section.

It is also entirely possible for you to create your own location technology. The S60 platform
allows applications to determine information such as the Cell ID of a connected mobile
network base station and the names of WLAN networks, along with signal strength
information. Such information could then be used, together with details from external or on-
device databases, to determine the device’s location. However, in general, employing such
methods is unnecessary.

Should you create a location estimation technology it is possible to add this to the S60
platform, or specific devices, using a plug-in architecture. However, access to the positioning
system plug-in APIs is controlled and would require the involvement of a device manufacturer.
Further discussion is beyond the scope of this booklet.


Location services in the S60 platform
S60 3rd Edition and S60 5th Edition offer their runtimes APIs that are positioning-method
independent. These APIs allow applications to acquire location information as well as manage
landmarks. This means that, beyond confirming that an S60 device can acquire location
information, an application does not need its own logic to determine a device’s location.
For example, without the framework, an application designed to use an external GPS receiver
would require you to design, implement, test and maintain modules for Bluetooth discovery
and connectivity, the receiver’s power management and NMEA strings parsing. By adopting the
framework you can rely on all these tasks being performed transparently by the middleware.
This allows more resources to be focused on the application’s logic, while also removing the
application’s dependency on a particular positioning technology.
7

Introducing the Mobile Location Framework
The S60 platform offers Symbian C++ developers location services through the Mobile Location
Framework (MLF). The MLF provides features to acquire location estimates, receive positioning
updates and manipulate landmarks. A key benefit of the MLF is that it provides a single set of
APIs for location acquisition using any of the supported positioning methods. The S60
platform adds a number of APIs to the core Symbian OS MLF that provides UIs for various
common landmark tasks, such as searching and selecting. The structure of the MLF is
illustrated in Figure 2.




              Figure 2: The Mobile Location Framework offered in S60 3rd Edition and beyond

The MLF offers two main functions: location acquisition and landmark management.

Location acquisition
The Location Acquisition APIs gain their information from the MLF Location Server. The Location
Server in turn uses the Positioning plug-in framework to determine what location technologies
are available. Once an acquisition plug-in has been selected, a positioning system (PSY) plug-
in (known as the ‘positioning modules’ to the API) is used to retrieve location estimates. The
Location Server also uses a Privacy Manager subsystem to validate whether an application has
the right to be provided with location estimates. This module is designed to validate remote
location requests (requests made by systems the device may be attached to). When such
requests are received, the Privacy Manager may block the request, ask for user verification or
allow the request. To enable the Privacy Manager in enforcing its rules, each location
information requestor must identify itself to the MLF. In addition, Symbian OS platform security
policies are enforced such that the requesting application must possess the Location capability
if it wants to connect to the MLF.

Note: In S60 3rd Edition, Feature Pack 2 and later, the Location capability can be granted by
the user when an application is installed. On earlier versions of the S60 platforms such
applications would need to be certified by Symbian Signed (www.symbiansigned.com).
8

The abstraction of the privacy management and location acquisition technologies through the
Location Server allows Symbian OS to provide Symbian C++ developers with a single set of
APIs for all location acquisition tasks. These APIs allow you to access information such as a
location estimate, to perform various location-based calculations, such as determining
distances, bearings and speeds between reference points, and to translate coordinates
between different systems.

Landmarks
The Landmarks APIs enable the user and all location-aware applications on an S60 device to
create, update, categorize, delete, send and receive points of interest (POIs) in shared or
private databases on the device. In addition, remote databases of POIs can also be connected
to and shared. From S60 3rd Edition a number of UI components are available to add features
to your applications for listing, editing and selecting landmarks based on user or application-
defined criteria. These UI components remove the need to create a custom UI for POI
management tasks.

Landmark information is transferred to and from an S60 device in a custom Landmark XML
(LMX) format file, using the MIME type
‘application/vnd.nokia.landmarkcollection+xml’. In addition, selected S60
3rd Edition devices have support for importing GPX format files, with this feature becoming
standard in S60 5th Edition and providing parsing support in CPosLandmarkParser. GPX
format files are identified by the MIME type ‘application/gps+xml’.

Landmark files can be sent and received via any available mechanism. This feature has a
number of uses, for example, landmarks can be embedded in a web page, site visitors can
then download the landmark to their phones and travel to the landmark using guidance from
the navigation software installed on the device.

Now you understand the basics of the location features offered by the S60 platform, we will
look in detail at how to use the Symbian C++ APIs to obtain location information and
manipulate landmarks.


Working with location information
The Location Acquisition API provides the mechanism by which an application can obtain
location estimates from one of the available PSYs. The API communicates with the Location
Server through the RPositionServer and RPositioner classes. RPositionServer
provides mechanisms to connect to the Location Server and fetch information about the
positioning technology modules available on the device, while RPositioner is used to query
location information with specific update options and to manage privacy.
9




      Figure 3: The basic steps involved in obtaining location information with the Location Acquisition API

Opening a session to the Location Server
Your first step in working with the Location Acquisition API is to open a session to the
Location Server using RPositionServer::Connect().

  void CLbsPositionRequestor::ConstructL()
  {
  ...
  // RPositionServer iPosServer (is defined elsewhere)
  // remember to Close() this session
  User::LeaveIfError(iPosServer.Connect());
  ...
  }

The RPositionServer handle can be used to query information on the various positioning
modules on the device via TPositionModuleInfo and TPositionModuleStatus
classes, and can start receiving updates on their status using the
TPositioningModuleStatusEvent class.

The code below iterates through the available positioning modules and gets the name of the
module to a descriptor.
10

void CLbsPositionRequestor::EnumerateTechnologies()
  {
  ...

  TPositionModuleInfo moduleinfo;
  TBuf<KPositionMaxModuleName> moduleName;

  TUint numOfModules = 0;
  iPosServer.GetNumModules( numOfModules );
  for( TUint i = 0; i < numOfModules; i++ )
    {
    // read current module info
    iPosServer.GetModuleInfoByIndex ( i, moduleinfo );
    // only if enabled by user
    if(moduleinfo.IsAvailable())
       {
       // read current module name
       moduleinfo.GetModuleName( moduleName );
       ...
       }
      ...
    }
  ...
  }

It should be noted that simply because a positioning module is available on a device, it does
not mean that your application can make use of it. The device user has the ability to
determine which positioning modules are enabled. For example, the user may disable an
integrated GPS to prevent accurate information on their location being made available to a
tracking application, or turn off a network-based positioning module to ensure location
estimation does not increase their over-the-air data usage.

Opening a location requestor handle
After setting up a session to the Location Server with RPositionServer, the
RPositioner class can be used to fetch location estimates from the Location Server.

RPositioner::Open() has a couple of overloads to provide control over the way in which
the Location Server provides information to an application. To utilize the default positioning
module on a device, the RPositionServer handle needs to be passed as the argument.
The default module can be identified by calling
RPositionServer::GetDefaultModuleId(). The RPositioner::Open() overload,
using positioning module selection criteria as an argument, is not supported in the S60
platform at the time of writing. The positioning module selection logic has to be implemented
using RPositionServer to query for the available modules and the features of
TPositionModuleInfo must be used to find out the most suitable module.

You can open a subsession to the Location Server using the default module by calling:

// RPositioner iPositioner (is defined elsewhere)
// remember to Close() this subsession
iPositioner.Open( iPosServer );
11

Alternatively, you can specify the module ID if you want to receive updates from a specific
positioning module, as follows:

// following the example where the module name was read
// ... we want to use that specific module
// remember to Close() this subsession
iPositioner.Open( iPosServer, moduleinfo.ModuleId() );

To work with multiple positioning modules, you need to open separate RPositioner
handles for each one before you can use the location estimate output provided by them. For
example, if you want to use the fast location estimate provided by a network-based
positioning system together with the GPS positioning module (to improve time-to-fix when
starting a location-based application), you will need to open both modules.

Identifying the requestor
To safeguard the privacy of a user, the Location Framework requires each requestor of location
information to identify themselves and handle the display of appropriate notifications to the user
if necessary. In practice, notifications of location information requests from C++ applications are
not pushed to the user in S60 3rd Edition, Feature Pack 1 and earlier devices, since the Symbian
OS platform security Location capability is needed by the requesting processes. This means
that applications must be Symbian Signed with the Location capability to make use of the
MLF. From S60 3rd Edition, Feature Pack 2 onwards, the Location capability is user grantable
and the user will be notified of the application’s desire to read location information during
installation. Such applications would therefore not require the application to be Symbian Signed.

Every requestor of location information must identify themselves to the Location Framework.
For example, if your application acts as a proxy for a web service requesting location
information, you need to specify your application and the identity of the service. This allows
the MLF’s Privacy Manager to apply the appropriate privacy rules to a location request. A
requestor may be specified as a service or a contact stored in the device’s contacts database
as appropriate. RPositioner provides methods to set either a single requestor or multiple
requestors, using the overloaded RPositioner::SetRequestor() call.

The requestor information can be set as follows:

_LIT(KRequestor, "MyService");
iPositioner.SetRequestor( CRequestor::ERequestorService,
           CRequestor::EFormatApplication, KRequestor );

Setting the update options and requests for position information updates
The Location Acquisition API provides a cached version of location information. This is useful
when your application has no need for periodic location updates or only needs to know the
last cached position. You call the asynchronous
RPositioner::GetLastKnownPosition() to get this information. Remember that in
Symbian OS asynchronous requests are issued by active objects, which are also responsible for
handling the request’s completion.

void CLbsPositionRequestor::RequestLKP()
  {
  ...
  // TRequestStatus and TPositionInfo member variables
  // Get last known position.
12

     // i.e CLbsPositionRequestor::RunL()
     // The result is processed in active object’s RunL method
     iPositioner.GetLastKnownPosition(*iPosInfoBase,iStatus);
     // Set this object active
     SetActive();
 }

Alternatively, you can register your application to receive position change notifications. Before
requesting position information updates, you need to specify the type, interval and validity of
position updates to be provided by the Location Server. You should do this as follows:

void CLbsPositionRequestor::SetOptions()
  {
  TPositionUpdateOptions updateops;
  // Set update interval to one second
  updateops.SetUpdateInterval(TTimeIntervalMicroSeconds(1000000));
  // If position server could not get position
  // In 15 seconds it will terminate the position request
  updateops.SetUpdateTimeOut(TTimeIntervalMicroSeconds(15000000));
  // Positions which have time stamp below 0.5 seconds can be reused
  updateops.SetMaxUpdateAge(TTimeIntervalMicroSeconds(500000));
  // Enables location framework to send partial position data,
  // for example allowing only a time stamp to be delivered
  // to the requestor if more complete updates are not available
  updateops.SetAcceptPartialUpdates(ETrue);

     // Set update options
     iPositioner.SetUpdateOptions( updateops );
     }

// A position update request is then started by calling
// RPositioner::NotifyPositionUpdate()
void CLbsPositionRequestor:: RequestPositionUpdates()
  {
  ...
  // The result is processed in active object’s RunL() method
  iPositioner.NotifyPositionUpdate(*iPosInfoBase, iStatus);

     // Set this object active
     SetActive();
     }

The result of the request is handled in the RunL() event handler of your active object. You
need to check for the success of the request by examining the request status variable and, on
successful request completions, act upon the updated position information (TPositionInfo,
TCourseInfo or HPositionGenericInfo).
13

...
void CLbsPositionRequestor::RunL()
  {
  switch ( iStatus.Int() )
    {
    // The fix is valid
    case KErrNone:
    // The fix has only partially valid information.
    // It is guaranteed to only have a valid timestamp
    case KPositionPartialUpdate:
      {
      ProcessPositionUpdate();
      // Issue a new request if needed
      RequestPositionUpdates();
      break;
      }
    // The data class used was not supported
    case KErrArgument:
    ....
    }
  }

After a position update notification has been received, the client application must re-issue the
request if it wishes to obtain further updates.

Cleaning up and tearing down
Requests issued with RPositioner and RPositionServer can be cancelled using their
CancelRequest() methods.

Subsession and session handles to the Location Server have to be closed by calling
RPositioner::Close() and RPositionServer::Close() respectively.

CLbsPositionRequestor::~CLbsPositionRequestor
  {
  ...
  //cancelling pending requests
  // Cancel() calls DoCancel() if the object is active

  // closing sessions
  iPositioner.Close();
  iPosServer.Close();
  ...
  }

Working with landmarks
The Landmarks API offers features to access, search and update landmarks databases residing
locally on the device or available online.

The CPosLandMarksDatabase class provides APIs for creating, opening and closing
databases as well as receiving notification of database management events. Once a database
is open, the CPosLandmarkSearch class and associated criteria classes are used to execute
a landmark search, and the CPosLandmarkParser and CPosLandmarkEncoder classes
can be used to import and export landmarks.
14

Three UI APIs are available to enable user interaction with the landmark information:
   • CLmkEditorDlg, which provides a dialog for editing landmark data
   • CLmkCategorySelectorDlg and CLmkLandmarkSelectorDlg, which provide
     selection dialogs.

The data edited with CLmkEditorDlg is automatically saved in the database when the
dialog is closed, so this dialog can be employed to allow the user to inspect and edit the
content of a new landmark before it is added to the database.

Accessing and manipulating databases
The CPosLandMarksDatabase class is used to access a landmarks database. The
Landmarks Database Management API provides facilities for listing databases as well as
creating and deleting databases. Clients can also subscribe to notifications on changes to a
landmarks database.

void CLandmarkManager::ConstructL()
  {
  ...
  // open the default landmarks database
  // CPosLandmarkDatabase* iDb (is defined elsewhere);
  iDb = CPosLandmarkDatabase::OpenL();
  InitializeIfNeededL();
  ...
  }

Landmarks database operations, such as searching within a large set of landmarks, are
potentially time consuming. To prevent such operations blocking the main application, it is
recommended that such tasks be broken into smaller sub tasks and run incrementally by
assigning an active object to run the task. The Landmark API provides the CPosLmOperation
object for such operations, as illustrated in this code used to initialize a landmarks database:

void   CLandmarkManager::InitializeIfNeededL()
  {
  //   check if landmarks database needs to be initialized
  //   run the initialization via CPosLmOperation object if necessary
  if   (iDb.IsInitializingNeeded())
     {
     // Create initialize operation
     // CPosLmOperation* iOperation
     // TReal32 iProgress (is defined elsewhere)
     iOperation = iDb.InitializeL();
     iOperation->NextStep( iStatus, iProgress );
     SetActive();
     }
  }
void CLandmarkManager::RunL()
  {
  if ( iStatus == KPosLmOperationNotComplete )
    {
15

      // The operation has not completed.
      // Use iProgress to indicate progress
      // Perform the next initialization step
      iOperation->NextStep( iStatus, iProgress );
      SetActive();
      }
      else
      { // The operation has completed.
      // check for potential errors here and handle the result
      }
  }

Operations that normally need to be run incrementally are possible using the ExecuteL()
and ExecuteAndDeleteLD() Landmarks API utility methods.

Searching landmarks
The Landmarks Search API enables searching of a landmarks database. Such searches can be
refined by defining names, categories, distance to a location, text values or any combination of
these criteria. The user can also refine a search result by applying new search criteria to the
cached result. The search is executed incrementally, with a similar execution model as
displayed in the code snippet provided in the previous section. Search operation results can
be sorted using criteria such as position or category and can be iterated through using the
returned CPosLmIterator object. If search results need to be displayed to the user during
the search, the display data functionality of the Landmarks Search API has to be used to
access the partial result set.

The code snippet below searches for landmarks with the word ‘flowers’ in their name. The
search is run in one step without displaying a progress dialog or incrementally reporting search
results.

void CLandmarkManager::ExamplifySearch()
  {
  _LIT(KSearchString, "flowers");

  ...

  // Create a search object and provide the CPosLandmarkDatabase
  // object.
  CPosLandmarkSearch* search = CPosLandmarkSearch::NewL(*iDb);
  CleanupStack::PushL(search);

  // Create the search criteria
  CPosLmTextCriteria* crit = CPosLmTextCriteria::NewLC();
  crit->SetTextL(KSearchString);

  // Start the search and execute it at once.
  ExecuteAndDeleteLD(search->StartLandmarkSearchL(*crit));
  CleanupStack::PopAndDestroy(crit);

  // Retrieve an iterator to access the matching landmarks.
  CPosLmItemIterator* iter = search->MatchIteratorL();
  CleanupStack::PushL(iter);
16

  // Iterate the search matches.
  TPosLmItemId lmID;
  while ((lmID = iter->NextL()) != KPosLmNullItemId)
    {
    CPosLandmark* lm = iDb->ReadLandmarkLC(lmID);

     // Do something with the landmark information
     ...

     CleanupStack::PopAndDestroy(lm);
     }

  // delete iterator and search objects
  CleanupStack::PopAndDestroy(2, search);
  ...
  }

Importing and exporting landmarks
The S60 platform provides for exchanging landmark data between users or applications on
different devices or computers using the LMX format. The CPosLandmarkEncoder and
CPosLandmarkParser classes are used to export and import landmarks.

The CPosLandmarkEncoder class either exports all landmarks or a subset based on an ID
array of the landmarks to be exported that are passed to the instantiated export object. If any
of the landmarks in the ID array are not present in the database, the entire export operation
will fail.

The code below shows how to export landmarks to a file using the
CPosLandmarkDatabase() method. In this example the incremental operations are
executed synchronously.

void CLandmarkManager::ExportSelectedLandmarksL(
       RArray<TPosLmItemId>& aSelectedLandmarks)
  {
  LIT( KExportFilePath, "c:eposLmExport.lmx" );

  // Mime type of landmarks exchange format
  _LIT8( KPosMimeTypeLandmarkCollectionXml,
    "application/vnd.nokia.landmarkcollection+xml" );

  // Create the encoder to be used for exporting landmarks
  CPosLandmarkEncoder* encoder =
  CPosLandmarkEncoder::NewL( KPosMimeTypeLandmarkCollectionXml );
  CleanupStack::PushL( encoder );

  // Point out the file to export landmark data to
  encoder->SetOutputFileL( KExportFilePath );

  // Execute the operation in one batch
  // Note: There must be landmarks for specified
  // IDs in the database,otherwise operation
17

  // will fail with KErrNotFound
  ExecuteAndDeleteLD( iDb->ExportLandmarksL(*encoder,
                                   aSelectedLandmarks,
         CPosLandmarkDatabase::EIncludeCategories ) );

  // Finalize encoding to complete export
  ExecuteAndDeleteLD( encoder->FinalizeEncodingL() );
  CleanupStack::PopAndDestroy( encoder );
  }

The import of landmark data is performed using the CPosLandmarkParser class. Imports
can be for all the landmarks in the source or for a subset defined by passing an array.

The code below imports landmarks from a file using the CPosLandmarkDatabase()
method.

void CLandmarkManager::ImportLandmarksL( const TDesC& aImportFilePath )
  {
  // Mime type of landmarks exchange format
  _LIT8( KPosMimeTypeLandmarkCollectionXml,
    "application/vnd.nokia.landmarkcollection+xml");

  // Create the parser to be used for importing landmarks
  CPosLandmarkParser* parser =
    CPosLandmarkParser::NewL( KPosMimeTypeLandmarkCollectionXml );
  CleanupStack::PushL( parser );

  // Point out the file to import landmark data from
  parser->SetInputFileL( aImportFilePath );
  CPosLmOperation* op = iDb->ImportLandmarksL(*parser,
              CPosLandmarkDatabase::EDefaultOptions );
  CleanupStack::PushL( op );
  // Execute the operation in one batch
  op->ExecuteL();

  // Fetch the landmark iterator of imported landmark IDs
  CPosLmItemIterator* iter = iDb->ImportedLandmarksIteratorL( op );
  CleanupStack::PushL( iter );

  // Fetch imported landmark data using this iterator
  // Iterate the search matches.
  TPosLmItemId lmID;
  while ((lmID = iter->NextL()) != KPosLmNullItemId)
    {
    CPosLandmark* lm = iDb->ReadLandmarkLC(lmID);

      // Do something with the landmark information
      ...
18


     CleanupStack::PopAndDestroy(lm);
     }

  // Cleanup
  CleanupStack::PopAndDestroy( iter );
  CleanupStack::PopAndDestroy( op );
  CleanupStack::PopAndDestroy( parser );
  }

As with other landmark operations, exports and imports can be run incrementally.

Viewing or editing landmarks
Landmarks can be viewed or edited using the Landmarks UI Add/Edit API, which also provides
features such as the option to send a landmark or view its location on a map (if a suitable
mapping application, such as Nokia Maps, is present on the device). Using the viewer or editor
requires the definition of a landmark to work with, either by creating a new one or using one
defined by a search result. The dialog is then launched in either viewer or editor mode.




             Figure 4: The Landmarks Add/Edit UI enables landmarks to be managed by the user

The code below launches a landmark viewer dialog for an existing landmark.

void CMyLmUiAppView::LaunchLmkViewerWithLmkIdL(TLmkItemIdDbCombiInfo
                                                           almItem)
  {
  //extract the database handle.
  CPosLandmarkDatabase* db =almItem.GetLmDb();
  //extract the seleted landmarks item id
  TPosLmItemId itemId = almItem.GetItemId();

  CLmkEditorDlg::TLmkEditorParams editParams;
  //set to make visible all the fields in viewer.
  editParams.iAttributes = CLmkEditorDlg::ELmkAll;
  //set to launch viewer
  editParams.iEditorMode = CLmkEditorDlg::ELmkViewer;
19

  CLmkEditorDlg *dlg = CLmkEditorDlg::NewL(*db,itemIdeditParams);
  // set Mop parent
  dlg->SetMopParent(this);

  dlg->ExecuteLD()
  }

Selecting landmarks
The Landmarks UI Selector API provides a mechanism to enable users to select landmarks or
categories from a list.




      Figure 5: The Landmarks UI Selector API enables the user to choose landmarks or landmark categories

Here is a simple code snippet that launches a dialog allowing a user to select multiple
landmarks.

void CMyLmUiAppView::LaunchLandmarksMultipleSelectorL()
  {
  CLmkLandmarkSelectorDlg* lmkSelectDlg =
         CLmkLandmarkSelectorDlg::NewL();
  lmkSelectDlg->SetMopParent(this);
  RArray<TLmkItemIdCombiInfo> selItemArray;
  TInt retVal = lmkSelectDlg->ExecuteLD( selItemArray );

  // Use selItemArray to get the IDs of the returned landmarks…
  // and a handle to the database they reside at
  }

Working with other features
There is one final feature of the location services: the BLID Application Satellite Info API. This
API allows information on the GPS satellites visible to the GPS hardware to be displayed.
20




         Figure 6: In S60 3rd Edition, Feature Pack 2 and later, the BLID Application Satellite Info API
                                    offers two views of satellite information

Other S60 platform runtimes
This booklet has concentrated on developing location-aware applications using Symbian C++;
however, this is not the only option. Java technology and Python offer developers location APIs
in S60 3rd Edition and later. Starting with S60 5th Edition, web widgets and Flash Lite
applications gain location APIs. These APIs are introduced in this section.

Java technology
The S60 platform offers a comprehensive set of Java Micro Edition (Java ME) APIs. Since the
introduction of S60 3rd Edition, these have included the Location API for J2ME (JSR-179). This
API provides methods for determining the current location, as well as creating and accessing
landmark information. A generalized view of the API is shown in Figure 7.




                                         LocationProvider                      LocationListener




                           Figure 7: The architecture of the Location API for Java ME
21

Retrieving a device’s location involves getting an instance of the LocationProvider object
and using this to retrieve location information. The example code below shows how this is
done. Note that Criteria is set to require the location fix to be accurate within 500 meters
and that a timeout on the retrieval of location data has been set at 60 seconds.

public void checkLocation() throws Exception
   {
      String string;
      Location l;
      LocationProvider lp;
      Coordinates c;

        Criteria cr= new Criteria();
        cr.setHorizontalAccuracy(500);

        lp= LocationProvider.getInstance(cr);
        l = lp.getLocation(60);

        c = l.getQualifiedCoordinates();
        if(c != null ) {
           // Use coordinate information
           double lat = c.getLatitude();
           double lon = c.getLongitude();
           string = "nLatitude : " + lat + "nLongitude : " + lon;
         } else {
           string ="Location API failed";
         }
         midlet.displayString(string);
    }

Applications created using JSR-179 have access to features similar to those offered by the MLF.
As such, Java technology offers an entirely suitable alternative to Symbian C++ for the creation
of sophisticated location-aware applications.

Web Runtime
With the introduction of S60 5th Edition, WRT has been given access to S60 location and
landmarks services through a JavaScript binding to S60 Platform Services. This enables
developers to perform such operations as acquiring a location, tracing location updates and
making location-based calculations, as well as searching and modifying landmark databases.

To obtain a device’s location, JavaScript code needs to declare a service object and then get
the required service to that object. There are several services offered by the S60 Platform
Services binding; others include access to device data such as Contacts and Calendar records.
The service object for location information is Service.Location of the type ILocation.

Once the object has been created, location information is obtained using the
GetLocation() function. Before the function is used, however, an object for criteria is
required. These criteria enable the control of the information returned. For example, by setting
PartialUpdates to False it is possible to force the request to return a complete set of
basic location details. This setting prevents incomplete information being returned if, for
example, a built-in GPS had not acquired a reliable fix when the request was initiated.

This code snippet shows how a simple widget uses these features to display a device’s
latitude and longitude, as shown in Figure 8. Note, however, that this code does not include
appropriate error checking.
22


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>My Location Aware Widget</title>

     <script type="text/javascript">
       window.onload = function() {
         var serviceObject =
           device.getServiceObject("Service.Location", "ILocation");
         var criteria = new Object();
         var result = serviceObject.ILocation.GetLocation(criteria);

           var latitude = result.ReturnValue.Latitude;
           var longitude = result.ReturnValue.Longitude;

           alert('Latitude= ' + latitude + 'nLongitude= ' +
             longitude);
       };
     </script>

  </head>
  <body>
  </body>
</html>

In addition to longitude and latitude, the variable returned from GetLocation() can provide
altitude, satellite, speed, course and heading data. The actual information provided depends
on the positioning technology in use on the device, for example, if network positioning is used
altitude would not be included in the result.

It is also possible to get location information asynchronously using a callback extension to
GetLocation().




     Figure 8: Location information displayed in an example widget running in the S60 5th Edition emulator
23


With the introduction of S60 Platform Services support to WRT, web developers can now create
location-based applications for S60 devices and offer features that were previously achievable
in Symbian C++ and Java applications only.

Flash Lite
With the introduction of S60 5th Edition, Flash Lite developers have access to location and
landmark services through an ActionScript binding to the S60 Platform Services. This feature
enables Flash Lite developers to perform such operations as acquiring a location, tracing
location updates and making location-based calculations as well as searching and modifying
landmark databases.

To use these features the ActionScript code needs to create a variable to hold a specific service
object, such as the location service. Once this is done another variable can be set to a specific
attribute of the service, such as location, as shown in the following code:

var so = new Service("Service.Location", "ILocation");
var location = so.GetLocation();

The variable returned from GetLocation() can provide longitude, latitude, altitude,
satellite, speed, course and heading data.

With the introduction of S60 Platform Services support to Flash Lite, developers can now
create location-based applications for S60 devices and offer features that were previously
achievable in Symbian C++ and Java applications only.

Python for S60
Python for S60 offers the ease and familiarity of the Python language to S60 application
developers. It is currently available as a plug-in for the S60 SDKs and Nokia devices based on
S60 3rd Edition or later. The plug-ins are obtained from the Python for S60 project hosted on
SourceForge (sourceforge.net/project/showfiles.php?group_id=154155).

Extensions provided in Python for S60 offer developers access to a wide range of native
Symbian OS and S60 features, including presentation using the native S60 UI.

Support for location-aware applications is provided through the dynamically loaded extension
modules, location and position.

The location module provides basic information from a mobile network, such as country
code and Cell ID. Location applications using this module would need to look up location
information based on Cell ID.

The position module provides developers with access to location information from an
external GPS, and for S60 3rd Edition, Feature Pack 2 or later devices, an internal GPS where
available.

Python for S60 does not offer the ability to create or use landmarks stored in an S60 device.

While Python for S60 is most commonly used for application prototyping, it offers developers
a practical alternative to Symbian C++ and the Java language for location-aware applications.
24

Building a complete application
While the S60 platform provides you with services for determining location and storing
landmarks, alone these are rarely sufficient to build a user friendly location-based application.
So whether you are building a fully fledged navigation solution or simply updating a user’s
location to a social networking web community, location needs to be given context.

Context options
Context will generally come from one of the following sources: mapping information,
navigation services, point of interest information, user-generated content and advertising.

Mapping information
The conventional context for a location is found on a map. However, the options for mapping
information are numerous. The two basic options are raster or vector-based. Raster maps allow
you to use the content you would see on conventional printed maps directly. Raster maps,
however, have the significant drawback of generally requiring more data to provide similar
information to vector maps. They also offer few options for displaying summary information in
overviews and zooming into details could result in pixilation, unless different raster images are
available for various zoom levels.

By contrast, vector maps generally require less data storage or transmission, and can offer
summary and detailed views from the same data set. In addition, vector maps can offer the
option to provide either 2D or 3D views.




  Figure 9: Raster maps are used in ViewRanger (www.viewranger.com) and vector maps are used in Nokia Maps

Navigation services
In many instances, the user of a location-aware application will want to travel from their
current location to a place they have identified with the application. To facilitate the user’s
travel an application can offer a navigation service. Such a service would allow the user to
define criteria for the route they want to select, for example, specifying whether they are using
a motor vehicle or walking and whether they wish to avoid certain transportation network
features, such as toll roads or motorways.
25




             Figure 10: Nokia Maps offers route planning and voice guided navigation of a route

The presentation of a route can be achieved in several ways: it may be highlighted on a map
with the user tracking their progress by comparing the route to their current location through
to offering directions on screen, possibly supplemented with voice commands.

Point of interest information
While a map provides a user with context to their location and, depending on the map used,
basic information on major features in the surrounding area, it rarely provides specific point of
interest (POI) information. So while a map can tell your user they are on a particular street, it
does not provide them with any information on the attractions or services offered on that
street.




                 Figure 11: Nokia Maps showing POIs in the vicinity of Earl’s Court, London

In addition, your user may wish to answer specific questions about their surroundings, such as
‘Where is the nearest restaurant?’ To do this, access is required to a database of POIs tagged
with descriptive information.
26

User-generated content
While user-generated content alone will rarely provide, at least initially, a full context to
locations, it is an engaging way of involving users in your application. User-generated content
can cover a range of media such as still images, video and sound recording, and textual
information describing the features of a location.




Figure 12: GyPSii (www.gypsii.com) enables its users to create content tagged with the location that the content is from

Advertising
While advertising alone may not provide the sort of information your users would find
palatable, it can be used with other context information to add value to your application and
generate additional revenue. To work effectively, the use of advertising needs to be balanced
with free or purchased content and could benefit from targeting specific user interests and
needs.




Figure 13: GyPSii (www.gypsii.com) incorporates location-based advertising unobtrusively within user-generated content
27

Ultimately, your final application will probably combine several of these context types. For
example, a social networking application may allow someone to find a restaurant which is
conveniently located for a group of friends to travel to, then user-generated content could
provide independent information on the quality of the restaurant or images of its facade,
advertising content could offer a discount voucher and finally a navigation service could guide
the friends to the restaurant.

Sourcing context data
The first step in adding context to your application is determining the needs of your users.
From this you can determine the nature and level of information required to provide an
appropriate context.

The provision of some context may be inherent within the application. Information on the
location of friends and family would be inherently available in an application designed to allow
the user to track those people.

User-generated content requires two enablers: a method for users to upload location-tagged
information and a mechanism to store and retrieve this information. Location-based
advertising, at least for now, would require a similar application-specific infrastructure.

For the remaining context information, maps, navigation services and POIs, there are options
for using an external provider. In fact, the sheer quantity of data and the transient nature of
location information, such as POIs, make the use of an external service almost the only
practical option. Even so, there are still several options to be considered, including:

   • Using an on-device, third-party map data and visualization application.
     In this case your application would rely on another application to provide the map
     visualization and other related services to the end user. Where available, this approach
     removes the burden of tasks such as map visualization and routing from your code. In
     addition, it can leverage that application’s map information download capabilities and
     use data the user has already downloaded to their device. It also means map information
     will be presented in a way that is familiar to the device user. The disadvantages of this
     approach are that you will have to limit your mapping capabilities to those offered by the
     application and such an application may not be available on all devices, or may offer
     different features on different licensees’ devices. Nokia Maps (www.nokia.com/maps)
     provides this capability to the built-in applications on Nokia S60 devices.

   • Using a web-based GIS service.
     This is a popular approach to building location-aware applications that relies on a service
     provider that offers mapping, POIs, routing and geocoding as a web service. This
     approach removes the burden of basic map data manipulation from your application, but
     your application may have to provide the presentation UI for any visualization or service,
     such as navigation. The licensing arrangements may also limit the ability to cache data,
     or the format of data supplied by the provider may result in higher network usage
     compared to other methods. Examples of companies offering this service include Google
     (code.google.com), deCarta (www.decarta.com) and MapTP
     (developer.navteq.com/site/global/zones/ms/index.jsp).

   • Embedding a third-party GIS engine.
     This approach is similar to the using a web-based GIS service; however, an on-device
     engine is used to perform the basic data acquisition and presentation tasks, hiding much
     of the complexity away from your application. The principal advantages of this approach
28

     are its flexibility compared to using a web-based GIS Service. it also guarantees that the
     same visualization and service options are available on all devices and you are in control
     of the UI and data presentation. At the time of writing, there are two products available
     for the S60 platform: AtlasCt Mobile Map API for J2ME (www.atlasct.com) and Carmenta
     Mobile engine for Symbian C++ (www.carmenta.com).

   • Building your own engine.
     This is the most complex solution as it involves using raw data from map data providers,
     such as TeleAtlas (www.teleatlas.com), Navteq (www.navteq.com), and regional or local
     providers, and creating an engine to manipulate that data to create imagery, POI, routing
     and other services. This approach is likely to be most useful for specialized applications,
     such as those using topographic data.

An architectural view of the various options is given in Figure 14.




          Figure 14: The options for implementing geospatial context information in your application

Context data storage and access
Having determined how geospatial information is to be sourced, you need to make one further
decision: how the user will access this information. Will the information be provided as a fixed
data set loaded and stored on the user’s device or will the data be delivered over-the-air when
it is needed?

Providing the user with a fixed data set on their device means that they incur no additional
costs for accessing the information, but this information will almost certainly become out of
date and may limit coverage to the specific areas loaded at the time of purchase. Accessing
the data live allows the user to have the most up-to-date information and extend data to new
geographical areas, but means they may incur costs for data traffic on their mobile network.

Generally, the most appropriate solution is a hybrid. This may involve accessing all information
over-the-air initially but then caching it on the device or offering some elements as fixed data,
such as providing a set of maps on-device but then accessing POI information over the network.
29

It is also possible that the selection of a particular geospatial service provider may, either
technically or contractually, limit the access and storage options.


Development and testing tools
S60 applications are developed on a PC using an S60 SDK in conjunction with Carbide.c++,
Microsoft Visual Studio with Carbide.vs or using command line tools. Once an application has
been coded it is initially compiled for an S60 emulator. Using an S60 emulator, the application
can be tested on a PC.

Testing is an essential part of any application development project. Running an application
with a representative sample of data is a straightforward, if sometimes non-trivial, task for
most applications. As location-aware applications rely on the physical location of a device, how
is testing possible without either severely restricting the test data set or incurring a significant
investment in S60 devices and travel?

The answer is simple. Positioning simulation tools are provided in the S60 SDK emulators and
for Nokia S60 devices to simulate location and route information through the Simulation PSY.
Using locations (a single point saved as a National Marine Electronics Association [NMEA]
format file) and routes (saved as Simulated Movement Format [SPS] format files), the
Simulation PSY provides data for testing an application.

Creating simulated location data
The first step in using the positioning simulation tools is creating suitable data. Here you have
two options: recording live data or creating entirely artificial data sets.

Test data from the real world
The advantage of using test data captured from the real world is that it can include the typical
inaccuracies that a user would encounter in using your application. To do this, you should
collect data in the NMEA format and then ensure that the file is saved with the extension .nme.

There are several ways to gather NMEA-dumps. Some GPS receivers may contain the
functionality to trace data. There are also a couple of methods, with software contributed by
the developer community, documented on the Forum Nokia Wiki: the article ‘NMEA (GPS)
Location Viewer’ (wiki.forum.nokia.com/index.php/NMEA_(GPS)_Location_Viewer) provides a
Python for S60 script that can be used to log NMEA data, while ‘NMEAXmit - a NMEA dumper
for S60 3rd Edition’ (wiki.forum.nokia.com/index.php/NMEAXmit_-
_a_NMEA_dumper_for_S60_3rd_Edition) provides a Symbian C++ application able to dump
NMEA data to a memory card or send it over a Bluetooth connection.

Using the positioning simulation route generator
The S60 3rd Edition or later emulators include the Route utility. This allows locations and
routes to be created manually.

Using the editor in the Route utility, as shown in Figure 15, routes can be created by entering
coordinates or by drawing a route in the plot window. A map can also be imported to provide
real world context to a location or route.
30




                   Figure 15: The Route utility allows locations and routes to be created

Once a location or route has been saved, it can be utilized by the application running in the
emulator or on a device.

Using the positioning simulation tool for testing
Once you have your test data, the positioning simulation tool provides the mechanism by
which you make the data available to your application, using the Simulation PSY.

The Simulation PSY and its configurator are included in the S60 SDKs; they are not on S60
devices by default. For devices, the tool consists of two SIS files
(SimulationPsy_ARMV5.sis [the PSY] and SimPsyConfigurator.sis [the
configurator]) that are provided in the SDK in the
epoc32S60toolsSimPSYConfigurator folder.

Note: The SIS files in the early S60 3rd Edition SDKs have expired certificates, so it is
recommended to use the files from the latest S60 SDK. Alternatively, the necessary files can be
downloaded from the Forum Nokia Wiki article, ‘S60 Platform: Positioning Simulation Tool’
(www.forum.nokia.com/info/sw.nokia.com/id/edf2e7be-223d-4b50-af98-
87e0cbe5d186/S60_3rd_Edition_Positioning_Simulation_Tool.html). In addition, at the time of
writing, the application installs on Nokia S60 devices only.

In the S60 emulator, the Simulation PSY can be launched from the landmarks application, as
shown in Figure 16, which is found in the Tools folder. On a device, the configurator can be
launched from the GPS data application, which is found either in the Tools or GPS folder. In the
appropriate application, select Options > Positioning Settings. (You can also access Positioning
Settings from the Settings application, usually found in the main menu or Tools folder, by
choosing General > Positioning.) In the Positioning screen, select Positioning methods. In the
Positioning methods screen the Simulation option will be shown (on the emulator this is the only
option). Now select Options > Settings and the SimPsyConfigurator screen will allow a NMEA or
SPS file to be selected. Three files are supplied with the tool. Once a simulation file has been
selected, its position information will be made available for use in your application.
31




          Figure 16: The steps in selecting a file for position or route simulation on an S60 emulator

To make your own data sets available to the Simulation PSY configurator for the S60 emulator,
store your files in the folder epoc32releasewinscwudebzsystemdata. When
working on a device, install them in the systemdata folder on the drive on which you
installed the positioning simulation tool. The NMEAXmit application (mentioned in the ‘Test
data from the real world’ section) can save data in the correct location so that it’s accessible to
the simulation tool.

On a device, if your application offers the user the ability to select the positioning method,
then this can be used to select the Simulation PSY. If your application simply connects to the
default PSY, then you should disable all the positioning methods except the Simulation PSY to
make the data available to your application. You can also explicitly connect to the Simulation
PSY using the code outlined in the ‘Opening a location requestor handle’ section.

Getting to market
The goal of most development projects is distribution of the resulting applications to as many
users as possible. Fortunately, there is a wide range of distribution channels available to
developers of S60 applications.

Independent channels
The channels easiest to enter are those that offer applications over the Internet. Channels such
as Handango (www.handango.com), GetJar (www.getjar.com) and Handmark
(www.handmark.com) offer developers a self-service mechanism; after creating an account,
developers can post applications directly to the site’s catalogue.

Some Internet-based channels, such as Nokia Software Market (www.softwaremarket.nokia.com),
have restrictions on the applications that can be posted. These restrictions include requiring
applications to be Symbian Signed or Java Verified. In addition, these sites may perform
independent tests to ensure an application works correctly on the supported devices before
applications are made available for purchase.

An interesting new option for content and application distribution is MOSH. MOSH is a user-
defined channel for the distribution of mobile content, allowing all developers (regardless of
content type) to distribute to a global market. As MOSH is a community site, it allows
developers to connect easily with both the mass market and niche user communities
worldwide. For more information visit the MOSH site (mosh.nokia.com).
32

Mobile network operators
Operator channels also offer good outlets for applications, especially for applications that are
relevant to a particular geographical market, but these channels tend to place applications into
their portfolio only after a vetting process.

System integrators
For services and applications targeted at enterprise use, large system integrators can serve as
a channel to target enterprises on a significant scale. Nokia for Business
(www.nokiaforbusiness.com) is a channel program designed for application developers to
target large system integrators and value-added resellers.

Device manufacturers
Device manufacturers are becoming increasingly aware of the importance of services and
applications and their role in creating value for the consumer. Nokia Download! is an
integrated channel that enables developers to deploy their applications and services via an on-
device application catalogue. For more information on Nokia-specific channels visit
www.forum.nokia.com/main/go_to_market/nokia_channels.html.

More information on market channels is provided in the Go to Market section of the Forum
Nokia site (www.forum.nokia.com/main/go_to_market) and the Developer section of the Nokia
site (www.nokia.com/developer). In addition, the Symbian Press booklet Getting to Market,
which can be found on the Symbian Press web site (developer.symbian.com/booklets),
provides a handy guide to finding a route to commercial success.

Getting further assistance
The Forum Nokia web site (www.forum.nokia.com) provides access to a vast range of technical
resources designed to help you make the most of the opportunities offered by the S60
platform. For specific information on location-based services there is a dedicated section within
Forum Nokia (www.forum.nokia.com/lbs). The community of S60 developers, along with Nokia
experts, also actively contributes to providing developers with support through the Forum
Nokia Developer Discussion Boards (discussion.forum.nokia.com) and the Forum Nokia Wiki
(wiki.forum.nokia.com).

Each of these Forum Nokia resources has its own dedicated location-based applications
section.

For situations that call for immediate support and issues not covered by the discussion boards
or wiki, Forum Nokia offers developers fee-based technical support. Developers can purchase
support on a case-by-case basis or buy a five-case package or an annual subscription. For
support throughout the development of a mobile application, the Forum Nokia Technical
Consultancy service is available to work closely with developers at every level and stage of the
project. For more information on professional support, visit the Technical Services section of
the Forum Nokia site (www.forum.nokia.com/support).

Forum Nokia technical support also offers developers the opportunity to take advantage of the
S60 API Partnering program. This program allows developers to use undocumented APIs in
various S60 devices. To request an API, a developer purchases a Partnering API Request from
the Forum Nokia e-store and submits a support request detailing the API or functionality
required.

Symbian also provides information for developers creating location-aware applications. For
documentation, discussion forums and a wiki about Symbian OS development, visit the
Symbian Developer Network site (developer.symbian.com).
Conclusion
The S60 platform offers you the ability to access location information easily and conveniently
from within your application. Using this information and combining it with geospatial
information provided by your application users, data providers or advertisers enables you to
offer your users a rich and enticing location-aware experience.

This booklet has provided you with background information on the market for location-aware
applications, the basics of location estimation technology, an introduction to the MLF and the
APIs available to use it, an overview of the support for location in other S60 runtimes,
information on the testing tools available, a guide to the additional geospatial data that can
provide context to a location and pointers to selling your application and getting further
assistance.

It is now up to you to find the right way to add location-awareness to your application and, no
doubt, add to the range of exciting and engaging location-aware applications for S60 devices.
Developer resources
Symbian Developer Network
developer.symbian.com

Symbian Developer Network Newsletter
developer.symbian.com/register

Community web sites

Forum Nokia
forum.nokia.com

MOTODEV
developer.motorola.com

Samsung Mobile Innovator
innovator.samsungmobile.com
New from




Common Design Patterns for Symbian OS:
The Foundations of Smartphone Software
                    Common Design Patterns for Symbian OS
                    introduces the common design patterns used
                    to implement a variety of applications and
                    services on Symbian OS. The book describes
                    patterns based on the architectural elements
                    of Symbian OS and discusses how patterns
                    suited for desktop software must be adapted
                    or even avoided on a mobile platform.




Multimedia on Symbian OS: Inside the Convergence Device
                    Combining the insights and experience of
                    subject experts within Symbian and the
                    third-party developer community, this book
                    will be an invaluable reference for anyone
                    working with multimedia on Symbian OS.
                    The authors provide details of the native
                    C++ APIs for accessing camera, video,
                    audio, image manipulation and radio tuner
                    functionality, and discuss best practice,
                    tips and tricks.



       Symbian Press: developer.symbian.com/books
from




Developing Software for Symbian OS, Second Edition
                   This second edition of Developing Software
                   for Symbian OS helps software developers
                   new to Symbian OS to create smartphone
                   applications. The original book has been
                   updated for Symbian OS v9 and now
                   includes a new chapter on application
                   signing and platform security, and updates
                   throughout for Symbian OS v9 and changes
                   to the development environment.




Quick Recipes on Symbian OS
                   This book aims to make it easier to
                   develop applications by describing a
                   number of common programming tasks
                   and providing clear explanations of how to
                   complete them. The recipes are divided by
                   technology, including graphics, multimedia,
                   location-based services, networking,
                   telephony, connectivity and messaging.

                   Full sample code is available for
                   download, so it can be used as a starting
                   point in your own projects.
from




For all Symbian C++ developers:
Symbian OS Communications Programming, 2nd Edition
by Iain Campbell

S60 Programming - A Tutorial Guide
by Coulton & Edwards

Symbian OS Explained
by Jo Stichbury

Symbian OS Internals
by Jane Sales

Symbian OS Platform Security
by Craig Heath

Smartphone Operating System Concepts with Symbian OS
by Mike Jipping

Accredited Symbian Developer Primer
by Jo Stichbury & Mark Jacobs
from




Published Booklets
A Guide to P.I.P.S.
Carbide.c++ v1.3
Coding Standards
Coding Tips
Coverity Prevent on Symbian OS
Data Sharing Tips
Essential S60 - Developers’ Guide
Essential UIQ - Getting Started
Getting Started
Getting to Market
Java ME on Symbian OS
Localization
.NET Development on S60
Performance Tips
Platform Security for all
Quick Recipes Taster

Translated Booklets
Chinese            Russian
Japanese           Persian
Korean             Italian
Spanish
Notes:
Notes:
Essential S60
  Creating Location-
  Aware Applications
 Why?             What?           Where?             How?



Adding location-awareness to S60 applications offers
significant possibilities for extending existing applications
or creating new ones. This Essential S60 booklet gives
background information about positioning technology
and location-aware applications, and also provides an
introduction to the S60 APIs for developers using
Symbian C++, Java ME, Web Runtime or Flash Lite.

Creating Location-Aware Applications is part of the
Essential S60 series, designed to provide information in
a handy format to S60 developers.




Symbian Press
Symbian Press publishes books designed to
communicate authoritative, timely, relevant and
practical information about Symbian OS and related
technologies. Information about the Symbian Press
series can be found at
developer.symbian.com/books

Weitere ähnliche Inhalte

Ähnlich wie S60 essentials lbs_v1_0_en

Symbian mobile operating system seminar report
Symbian mobile operating system seminar reportSymbian mobile operating system seminar report
Symbian mobile operating system seminar reportDevesh Singh
 
Mobile Application Development
Mobile Application Development Mobile Application Development
Mobile Application Development nandhini seo
 
Smart Apps Review
Smart Apps ReviewSmart Apps Review
Smart Apps ReviewNoel Hatch
 
Enough_Software_Guide_16thEdition_Web
Enough_Software_Guide_16thEdition_WebEnough_Software_Guide_16thEdition_Web
Enough_Software_Guide_16thEdition_WebMarco Tabor
 
S60 - Over the air
S60 - Over the airS60 - Over the air
S60 - Over the airNokia
 
Seminar report on Symbian OS
Seminar report on Symbian OSSeminar report on Symbian OS
Seminar report on Symbian OSDarsh Kotecha
 
Navigation & Location Europe 2009 Condensed
Navigation & Location Europe 2009 CondensedNavigation & Location Europe 2009 Condensed
Navigation & Location Europe 2009 CondensedAlex Housley
 
Symbian applications development
Symbian applications developmentSymbian applications development
Symbian applications developmentJoe_Mason
 
Sample Guide for Writing Website Development Proposal
Sample Guide for Writing Website Development ProposalSample Guide for Writing Website Development Proposal
Sample Guide for Writing Website Development ProposalPatrick Ogbuitepu
 
Mobile app developers guide
Mobile app developers guideMobile app developers guide
Mobile app developers guidePrayukth K V
 
Whitepaper - Native App or HTML5
Whitepaper - Native App or HTML5Whitepaper - Native App or HTML5
Whitepaper - Native App or HTML5Dan Vitoriano
 
Marketing - ShrinkRay
Marketing - ShrinkRayMarketing - ShrinkRay
Marketing - ShrinkRayBLUERUSH
 
Mobile Developer's Guide To The Galaxy, 14th Edition
Mobile Developer's Guide To The Galaxy, 14th EditionMobile Developer's Guide To The Galaxy, 14th Edition
Mobile Developer's Guide To The Galaxy, 14th EditionMarco Tabor
 
Deploying+Mobile+Uc+For+Cisco
Deploying+Mobile+Uc+For+CiscoDeploying+Mobile+Uc+For+Cisco
Deploying+Mobile+Uc+For+CiscoLamont Taylor
 
Mobile Monday Silicon Valley 6/1/09 - LBS App Demos
Mobile Monday Silicon Valley 6/1/09 - LBS App DemosMobile Monday Silicon Valley 6/1/09 - LBS App Demos
Mobile Monday Silicon Valley 6/1/09 - LBS App Demoskateimbach
 
The Ultimate Guide on How to Launch Your Own Mobile App!
The Ultimate Guide on How to Launch Your Own Mobile App!The Ultimate Guide on How to Launch Your Own Mobile App!
The Ultimate Guide on How to Launch Your Own Mobile App!John Andric
 
Application Of A Mobile Application
Application Of A Mobile ApplicationApplication Of A Mobile Application
Application Of A Mobile ApplicationHeather Harvey
 
A Mobile Centric View of Silicon Valley - January 2011
A Mobile Centric View of Silicon Valley - January 2011A Mobile Centric View of Silicon Valley - January 2011
A Mobile Centric View of Silicon Valley - January 2011Lars Kamp
 
Security Application for Smart Phones and other Mobile Devices
Security Application for Smart Phones and other Mobile DevicesSecurity Application for Smart Phones and other Mobile Devices
Security Application for Smart Phones and other Mobile DevicesŃirjhor Ánjum
 
Building web apps for a multiscreen world
Building web apps for a multiscreen worldBuilding web apps for a multiscreen world
Building web apps for a multiscreen worldAussie
 

Ähnlich wie S60 essentials lbs_v1_0_en (20)

Symbian mobile operating system seminar report
Symbian mobile operating system seminar reportSymbian mobile operating system seminar report
Symbian mobile operating system seminar report
 
Mobile Application Development
Mobile Application Development Mobile Application Development
Mobile Application Development
 
Smart Apps Review
Smart Apps ReviewSmart Apps Review
Smart Apps Review
 
Enough_Software_Guide_16thEdition_Web
Enough_Software_Guide_16thEdition_WebEnough_Software_Guide_16thEdition_Web
Enough_Software_Guide_16thEdition_Web
 
S60 - Over the air
S60 - Over the airS60 - Over the air
S60 - Over the air
 
Seminar report on Symbian OS
Seminar report on Symbian OSSeminar report on Symbian OS
Seminar report on Symbian OS
 
Navigation & Location Europe 2009 Condensed
Navigation & Location Europe 2009 CondensedNavigation & Location Europe 2009 Condensed
Navigation & Location Europe 2009 Condensed
 
Symbian applications development
Symbian applications developmentSymbian applications development
Symbian applications development
 
Sample Guide for Writing Website Development Proposal
Sample Guide for Writing Website Development ProposalSample Guide for Writing Website Development Proposal
Sample Guide for Writing Website Development Proposal
 
Mobile app developers guide
Mobile app developers guideMobile app developers guide
Mobile app developers guide
 
Whitepaper - Native App or HTML5
Whitepaper - Native App or HTML5Whitepaper - Native App or HTML5
Whitepaper - Native App or HTML5
 
Marketing - ShrinkRay
Marketing - ShrinkRayMarketing - ShrinkRay
Marketing - ShrinkRay
 
Mobile Developer's Guide To The Galaxy, 14th Edition
Mobile Developer's Guide To The Galaxy, 14th EditionMobile Developer's Guide To The Galaxy, 14th Edition
Mobile Developer's Guide To The Galaxy, 14th Edition
 
Deploying+Mobile+Uc+For+Cisco
Deploying+Mobile+Uc+For+CiscoDeploying+Mobile+Uc+For+Cisco
Deploying+Mobile+Uc+For+Cisco
 
Mobile Monday Silicon Valley 6/1/09 - LBS App Demos
Mobile Monday Silicon Valley 6/1/09 - LBS App DemosMobile Monday Silicon Valley 6/1/09 - LBS App Demos
Mobile Monday Silicon Valley 6/1/09 - LBS App Demos
 
The Ultimate Guide on How to Launch Your Own Mobile App!
The Ultimate Guide on How to Launch Your Own Mobile App!The Ultimate Guide on How to Launch Your Own Mobile App!
The Ultimate Guide on How to Launch Your Own Mobile App!
 
Application Of A Mobile Application
Application Of A Mobile ApplicationApplication Of A Mobile Application
Application Of A Mobile Application
 
A Mobile Centric View of Silicon Valley - January 2011
A Mobile Centric View of Silicon Valley - January 2011A Mobile Centric View of Silicon Valley - January 2011
A Mobile Centric View of Silicon Valley - January 2011
 
Security Application for Smart Phones and other Mobile Devices
Security Application for Smart Phones and other Mobile DevicesSecurity Application for Smart Phones and other Mobile Devices
Security Application for Smart Phones and other Mobile Devices
 
Building web apps for a multiscreen world
Building web apps for a multiscreen worldBuilding web apps for a multiscreen world
Building web apps for a multiscreen world
 

S60 essentials lbs_v1_0_en

  • 1. Essential S60 Creating Location - Aware Applications
  • 3. Creating Location-Aware Applications part of the Essential S60 series 1st edition, 10/08 Published by: Symbian Software Limited 2-6 Boundary Row Southwark London SE1 8HP UK www.symbian.com Trademarks, copyright, disclaimer ‘Symbian’, ‘Symbian OS’ and other associated Symbian marks are all trademarks of Symbian Software Ltd. Symbian acknowledges the trademark rights of all third parties referred to in this material. Copyright © Symbian Software Ltd 2008. All rights reserved. No part of this material may be reproduced without the express written permission of Symbian Software Ltd. Symbian Software Ltd makes no warranty or guarantee about the suitability or the accuracy of the information contained in this document. The information contained in this document is for general information purposes only and should not be used or relied upon for any other purpose whatsoever. Compiled by: Richard Bloor Reviewed by: Petro Soininen Alexey Gusev Husham Hamdan Managing Editor: Pekka Kosonen Ashlee Godwin Heikki Rasimaki Jo Stichbury Jure Sustersic Lucian Tomuta
  • 4. 1 Contents Introduction.................................................................................................................................2 Location-based services on mobile devices ...............................................................................3 A background to positioning technology....................................................................................4 Satellite-based methods .........................................................................................................4 Terrestrial-based methods .......................................................................................................5 Mixed methods........................................................................................................................6 Positioning methods supported by the S60 platform ............................................................6 Location services in the S60 platform ........................................................................................6 Introducing the Mobile Location Framework...........................................................................7 Working with location information..........................................................................................8 Working with landmarks ........................................................................................................13 Working with other features ..................................................................................................19 Other S60 platform runtimes ....................................................................................................20 Java technology .....................................................................................................................20 Web Runtime..........................................................................................................................21 Flash Lite ...............................................................................................................................23 Python for S60 ......................................................................................................................23 Building a complete application ...............................................................................................24 Context options.....................................................................................................................24 Sourcing context data ...........................................................................................................27 Context data storage and access ..........................................................................................28 Development and testing tools ................................................................................................29 Creating simulated location data ..........................................................................................29 Using the positioning simulation tool for testing.................................................................30 Getting to market ......................................................................................................................31 Independent channels ...........................................................................................................31 Mobile network operators .....................................................................................................32 System integrators ................................................................................................................32 Device manufacturers ............................................................................................................32 Getting further assistance .........................................................................................................32 Conclusion.................................................................................................................................33 Developer resources..................................................................................................................34 Community web sites ............................................................................................................34
  • 5. 2 Introduction In an increasingly mobile world the desire to understand one’s surroundings and connect with work colleagues, friends and family is growing among mobile device users. If the content of your application relates to locations in the physical world, your users are going to expect the application to be location-aware. At the same time, an increasing proportion of S60 devices are shipping with integrated GPS. This means that accurate information on a device’s location is often readily available. However, even if a device does not include a GPS chip, many devices implement other methods of obtaining location information. To enable you to harness location information, S60 3rd Edition and S60 5th Edition (based on Symbian OS v9.1 to v9.4) provide an easy to use set of APIs for Symbian C++, Java ME and Python for S60. S60 5th Edition also offers you the ability to access location information in Flash Lite from Adobe and Web Runtime (WRT). These APIs are built around a common Mobile Location Framework (MLF). This booklet provides information on: • the location-aware application market • location estimation technologies • the Symbian C++ location APIs • location APIs in other S60 platform runtimes • the factors to consider when making your application location-aware • development tools to assist with testing. If you’re a developer looking to implement an LBS application for S60 devices, this Essential S60 booklet is for you. While a significant portion of this booklet is dedicated to Symbian C++ coding, if you want to use another S60 runtime — such as Java ME, WRT or Flash Lite — you will still find plenty of useful information throughout the booklet. In addition, specific coding information for other runtimes is provided in the ‘Other S60 platform runtimes’ section. You will also find more documentation on Forum Nokia’s web site (www.forum.nokia.com) about the LBS services provided by your chosen runtime. When you finish reading this booklet you will be ready to start making your applications for the S60 platform location-aware.
  • 6. 3 Location-based services on mobile devices The location-aware applications market is not new: enterprise and professional applications have been around for many years. However, the availability of inexpensive, small, low-power GPS chips and reliable network-based location technologies has moved the industry into a growth phase (see Figure 1). Figure 1: The location-aware application market is in a growth phase Location-aware software covers a very broad range of applications, including: • navigation and route finding • location-based information, such as services providing information on points of interest • professional and enterprise, such as fleet management, vehicle dispatch, vehicle tracking and personnel tracking • community, such as friend locators and location-based sharing of pictures and information • entertainment, such as location-aware games • safety, such as child tracking, theft tracking and emergency location. A survey conducted by CJ Driscoll and Associates (www.cjdriscoll.com) in 2006 found that of the ten most desired non-voice applications for mobile devices, half were location-based. The launch of the Nokia N95 multimedia computer, the first S60 device with an integrated GPS, helped sales of location-aware applications from Nokia Software Market grow by over 500% during 2007.1 So, mobile device users are clearly interested in and are willing to purchase location-aware applications. 1 See www.symbianone.com/content/view/5119/31 for further information.
  • 7. 4 This opportunity has been recognized by many of the companies that offered mapping and navigation services on dedicated GPS devices and as services to businesses. As a result there is already a wealth of navigation and local discovery applications available for S60 devices. As the market matures, S60 applications are appearing across many of the location-aware market categories. This does not, however, mean that the opportunities for new location-based S60 applications are limited. The first wave of location-based applications largely involved transplanting existing functionality into an S60 application. The second wave will combine location information with other information in unique and innovative ways to truly take advantage of the capabilities of mobile devices and fulfil the needs of mobile device users. These opportunities exist as strongly in the consumer market as they do in business applications. Consider the following possibilities: • An events calendar that allows users to find events by date and proximity, then provides navigation information to assist travel to an event. • A car park finder application that allows the user to identify suitable car parking at a location they are driving to, reserves a parking space and then provides directions to the car park. • An application that allows users to find the best price for a product based on the purchase cost and the cost of travel to the shop. The user could look for several products and the application could find the best route to balance travel costs with purchase prices. • A personal management application that could keep track of the user’s travel between diary events and automatically alert meeting attendees of a delay if traffic congestion is holding up the user. Hopefully these examples will have fired your imagination to recognize that there are still many possibilities for location-based applications and games, and many ways in which existing applications could benefit from location-awareness. A background to positioning technology The essential information a location-aware application needs is, rather obviously, information on location. There are several methods available for determining location and two basic technologies: satellite-based and terrestrial radio, as well as hybrid approaches that combine the best features of these two basic technologies. Each has its advantages and disadvantages, which we will review now. Satellite-based methods These methods rely on using information supplied by a network of medium earth orbit satellites. At the time of writing, this effectively means NAVSTAR-GPS, created by the United States Department of Defense, but which is generally referred to as the Global Positioning System (GPS). Other systems are in the process of being constructed or planned, such as the Russian GLONASS and the European Galileo positioning systems. In simplistic terms, a GPS receiver estimates its location by determining its distance from at least four GPS satellites. These distances are found using information on when a signal was transmitted by a satellite and its location at that time. Knowing these distances, the GPS receiver’s software can determine its location.
  • 8. 5 The advantages of GPS-based location determination are that: • it is free (once the necessary hardware has been obtained) • it does not rely on the device being connected to a radio network • it is very accurate where signals from the satellites can be received (typically within tens of meters for consumer GPS receivers). The principal disadvantages of GPS are that: • it requires dedicated hardware • it may not work in all locations. GPS receivers cannot be used to determine location indoors, in built-up areas with a high density of tall buildings, or in some natural locations such as canyons or steep sided valleys • GPS systems do not necessarily provide an instant response, requiring time to locate satellite signals when first requested for a location • integrated GPS hardware can have an appreciable effect on a device’s power consumption. This may need to be considered during the design of applications where prolonged use of an internal GPS receiver is likely. Terrestrial-based methods These methods rely on information a device can gather about terrestrial-radio networks. For mobile devices this means mobile network base stations, but WiFi and Bluetooth technology hotspots could also be used. If a device can determine the source of any radio signals and their strength then an estimate of location can be made, but only if the location of the source is already recorded. The advantages of terrestrial radio-based methods are that: • they do not rely on specific GPS location hardware and so can be used by any mobile device • these methods can often be the most accurate for determining location in built up areas. In these areas satellite systems may be ineffective because buildings obscure their signals, while terrestrial radio methods benefit from a high density of mobile network base stations, which can be supplemented with information from the often numerous WLAN networks. The disadvantages of these methods are that: • their accuracy can be low. Where there are a limited number of radio sources available, accuracy may be measured in kilometers • they are unable to provide altitude information • terrestrial radio-based methods rely on the availability of information on the location of radio sources and, where possible, information on the signal strength footprint or the use of techniques for determining the time a signal takes to arrive. As a result, these methods rely on either a database stored on the device, one accessed over-the-air or a combined method that caches relevant information on the device. A fixed on-device database will become less relevant over time, while use of an external database could result in the device user paying network charges to access it.
  • 9. 6 Mixed methods Mixed location technologies attempt to take advantage of the best characteristics of terrestrial radio and satellite-based positioning methods to improve the accuracy, time-to-first-fix or availability of positioning information. Several different mixed method technologies are available, including Assisted GPS System (A- GPS) and Differential Global Positioning System (DGPS). Their operation is generally similar, using the best available information to determine location, for example, an A-GPS system may use Secure User Plane Location (SUPL) (an Open Mobile Alliance [OMA] standard for transferring location information) to estimate a location based on information from the cellular network. This enables improved time-to-first-fix (when a location request is first made and a GPS is searching for satellites or when the signals available to the GPS are weak or incomplete). Positioning methods supported by the S60 platform At the time of writing, the S60 platform supports all three methods of location determination in the following forms: • external Bluetooth GPS • built-in GPS • A-GPS (using a built-in GPS) • network (terrestrial radio)-based triangulation. In addition, a method of simulating location is also supported for testing purposes; this method is discussed later in the ‘Development and testing tools’ section. It is also entirely possible for you to create your own location technology. The S60 platform allows applications to determine information such as the Cell ID of a connected mobile network base station and the names of WLAN networks, along with signal strength information. Such information could then be used, together with details from external or on- device databases, to determine the device’s location. However, in general, employing such methods is unnecessary. Should you create a location estimation technology it is possible to add this to the S60 platform, or specific devices, using a plug-in architecture. However, access to the positioning system plug-in APIs is controlled and would require the involvement of a device manufacturer. Further discussion is beyond the scope of this booklet. Location services in the S60 platform S60 3rd Edition and S60 5th Edition offer their runtimes APIs that are positioning-method independent. These APIs allow applications to acquire location information as well as manage landmarks. This means that, beyond confirming that an S60 device can acquire location information, an application does not need its own logic to determine a device’s location. For example, without the framework, an application designed to use an external GPS receiver would require you to design, implement, test and maintain modules for Bluetooth discovery and connectivity, the receiver’s power management and NMEA strings parsing. By adopting the framework you can rely on all these tasks being performed transparently by the middleware. This allows more resources to be focused on the application’s logic, while also removing the application’s dependency on a particular positioning technology.
  • 10. 7 Introducing the Mobile Location Framework The S60 platform offers Symbian C++ developers location services through the Mobile Location Framework (MLF). The MLF provides features to acquire location estimates, receive positioning updates and manipulate landmarks. A key benefit of the MLF is that it provides a single set of APIs for location acquisition using any of the supported positioning methods. The S60 platform adds a number of APIs to the core Symbian OS MLF that provides UIs for various common landmark tasks, such as searching and selecting. The structure of the MLF is illustrated in Figure 2. Figure 2: The Mobile Location Framework offered in S60 3rd Edition and beyond The MLF offers two main functions: location acquisition and landmark management. Location acquisition The Location Acquisition APIs gain their information from the MLF Location Server. The Location Server in turn uses the Positioning plug-in framework to determine what location technologies are available. Once an acquisition plug-in has been selected, a positioning system (PSY) plug- in (known as the ‘positioning modules’ to the API) is used to retrieve location estimates. The Location Server also uses a Privacy Manager subsystem to validate whether an application has the right to be provided with location estimates. This module is designed to validate remote location requests (requests made by systems the device may be attached to). When such requests are received, the Privacy Manager may block the request, ask for user verification or allow the request. To enable the Privacy Manager in enforcing its rules, each location information requestor must identify itself to the MLF. In addition, Symbian OS platform security policies are enforced such that the requesting application must possess the Location capability if it wants to connect to the MLF. Note: In S60 3rd Edition, Feature Pack 2 and later, the Location capability can be granted by the user when an application is installed. On earlier versions of the S60 platforms such applications would need to be certified by Symbian Signed (www.symbiansigned.com).
  • 11. 8 The abstraction of the privacy management and location acquisition technologies through the Location Server allows Symbian OS to provide Symbian C++ developers with a single set of APIs for all location acquisition tasks. These APIs allow you to access information such as a location estimate, to perform various location-based calculations, such as determining distances, bearings and speeds between reference points, and to translate coordinates between different systems. Landmarks The Landmarks APIs enable the user and all location-aware applications on an S60 device to create, update, categorize, delete, send and receive points of interest (POIs) in shared or private databases on the device. In addition, remote databases of POIs can also be connected to and shared. From S60 3rd Edition a number of UI components are available to add features to your applications for listing, editing and selecting landmarks based on user or application- defined criteria. These UI components remove the need to create a custom UI for POI management tasks. Landmark information is transferred to and from an S60 device in a custom Landmark XML (LMX) format file, using the MIME type ‘application/vnd.nokia.landmarkcollection+xml’. In addition, selected S60 3rd Edition devices have support for importing GPX format files, with this feature becoming standard in S60 5th Edition and providing parsing support in CPosLandmarkParser. GPX format files are identified by the MIME type ‘application/gps+xml’. Landmark files can be sent and received via any available mechanism. This feature has a number of uses, for example, landmarks can be embedded in a web page, site visitors can then download the landmark to their phones and travel to the landmark using guidance from the navigation software installed on the device. Now you understand the basics of the location features offered by the S60 platform, we will look in detail at how to use the Symbian C++ APIs to obtain location information and manipulate landmarks. Working with location information The Location Acquisition API provides the mechanism by which an application can obtain location estimates from one of the available PSYs. The API communicates with the Location Server through the RPositionServer and RPositioner classes. RPositionServer provides mechanisms to connect to the Location Server and fetch information about the positioning technology modules available on the device, while RPositioner is used to query location information with specific update options and to manage privacy.
  • 12. 9 Figure 3: The basic steps involved in obtaining location information with the Location Acquisition API Opening a session to the Location Server Your first step in working with the Location Acquisition API is to open a session to the Location Server using RPositionServer::Connect(). void CLbsPositionRequestor::ConstructL() { ... // RPositionServer iPosServer (is defined elsewhere) // remember to Close() this session User::LeaveIfError(iPosServer.Connect()); ... } The RPositionServer handle can be used to query information on the various positioning modules on the device via TPositionModuleInfo and TPositionModuleStatus classes, and can start receiving updates on their status using the TPositioningModuleStatusEvent class. The code below iterates through the available positioning modules and gets the name of the module to a descriptor.
  • 13. 10 void CLbsPositionRequestor::EnumerateTechnologies() { ... TPositionModuleInfo moduleinfo; TBuf<KPositionMaxModuleName> moduleName; TUint numOfModules = 0; iPosServer.GetNumModules( numOfModules ); for( TUint i = 0; i < numOfModules; i++ ) { // read current module info iPosServer.GetModuleInfoByIndex ( i, moduleinfo ); // only if enabled by user if(moduleinfo.IsAvailable()) { // read current module name moduleinfo.GetModuleName( moduleName ); ... } ... } ... } It should be noted that simply because a positioning module is available on a device, it does not mean that your application can make use of it. The device user has the ability to determine which positioning modules are enabled. For example, the user may disable an integrated GPS to prevent accurate information on their location being made available to a tracking application, or turn off a network-based positioning module to ensure location estimation does not increase their over-the-air data usage. Opening a location requestor handle After setting up a session to the Location Server with RPositionServer, the RPositioner class can be used to fetch location estimates from the Location Server. RPositioner::Open() has a couple of overloads to provide control over the way in which the Location Server provides information to an application. To utilize the default positioning module on a device, the RPositionServer handle needs to be passed as the argument. The default module can be identified by calling RPositionServer::GetDefaultModuleId(). The RPositioner::Open() overload, using positioning module selection criteria as an argument, is not supported in the S60 platform at the time of writing. The positioning module selection logic has to be implemented using RPositionServer to query for the available modules and the features of TPositionModuleInfo must be used to find out the most suitable module. You can open a subsession to the Location Server using the default module by calling: // RPositioner iPositioner (is defined elsewhere) // remember to Close() this subsession iPositioner.Open( iPosServer );
  • 14. 11 Alternatively, you can specify the module ID if you want to receive updates from a specific positioning module, as follows: // following the example where the module name was read // ... we want to use that specific module // remember to Close() this subsession iPositioner.Open( iPosServer, moduleinfo.ModuleId() ); To work with multiple positioning modules, you need to open separate RPositioner handles for each one before you can use the location estimate output provided by them. For example, if you want to use the fast location estimate provided by a network-based positioning system together with the GPS positioning module (to improve time-to-fix when starting a location-based application), you will need to open both modules. Identifying the requestor To safeguard the privacy of a user, the Location Framework requires each requestor of location information to identify themselves and handle the display of appropriate notifications to the user if necessary. In practice, notifications of location information requests from C++ applications are not pushed to the user in S60 3rd Edition, Feature Pack 1 and earlier devices, since the Symbian OS platform security Location capability is needed by the requesting processes. This means that applications must be Symbian Signed with the Location capability to make use of the MLF. From S60 3rd Edition, Feature Pack 2 onwards, the Location capability is user grantable and the user will be notified of the application’s desire to read location information during installation. Such applications would therefore not require the application to be Symbian Signed. Every requestor of location information must identify themselves to the Location Framework. For example, if your application acts as a proxy for a web service requesting location information, you need to specify your application and the identity of the service. This allows the MLF’s Privacy Manager to apply the appropriate privacy rules to a location request. A requestor may be specified as a service or a contact stored in the device’s contacts database as appropriate. RPositioner provides methods to set either a single requestor or multiple requestors, using the overloaded RPositioner::SetRequestor() call. The requestor information can be set as follows: _LIT(KRequestor, "MyService"); iPositioner.SetRequestor( CRequestor::ERequestorService, CRequestor::EFormatApplication, KRequestor ); Setting the update options and requests for position information updates The Location Acquisition API provides a cached version of location information. This is useful when your application has no need for periodic location updates or only needs to know the last cached position. You call the asynchronous RPositioner::GetLastKnownPosition() to get this information. Remember that in Symbian OS asynchronous requests are issued by active objects, which are also responsible for handling the request’s completion. void CLbsPositionRequestor::RequestLKP() { ... // TRequestStatus and TPositionInfo member variables // Get last known position.
  • 15. 12 // i.e CLbsPositionRequestor::RunL() // The result is processed in active object’s RunL method iPositioner.GetLastKnownPosition(*iPosInfoBase,iStatus); // Set this object active SetActive(); } Alternatively, you can register your application to receive position change notifications. Before requesting position information updates, you need to specify the type, interval and validity of position updates to be provided by the Location Server. You should do this as follows: void CLbsPositionRequestor::SetOptions() { TPositionUpdateOptions updateops; // Set update interval to one second updateops.SetUpdateInterval(TTimeIntervalMicroSeconds(1000000)); // If position server could not get position // In 15 seconds it will terminate the position request updateops.SetUpdateTimeOut(TTimeIntervalMicroSeconds(15000000)); // Positions which have time stamp below 0.5 seconds can be reused updateops.SetMaxUpdateAge(TTimeIntervalMicroSeconds(500000)); // Enables location framework to send partial position data, // for example allowing only a time stamp to be delivered // to the requestor if more complete updates are not available updateops.SetAcceptPartialUpdates(ETrue); // Set update options iPositioner.SetUpdateOptions( updateops ); } // A position update request is then started by calling // RPositioner::NotifyPositionUpdate() void CLbsPositionRequestor:: RequestPositionUpdates() { ... // The result is processed in active object’s RunL() method iPositioner.NotifyPositionUpdate(*iPosInfoBase, iStatus); // Set this object active SetActive(); } The result of the request is handled in the RunL() event handler of your active object. You need to check for the success of the request by examining the request status variable and, on successful request completions, act upon the updated position information (TPositionInfo, TCourseInfo or HPositionGenericInfo).
  • 16. 13 ... void CLbsPositionRequestor::RunL() { switch ( iStatus.Int() ) { // The fix is valid case KErrNone: // The fix has only partially valid information. // It is guaranteed to only have a valid timestamp case KPositionPartialUpdate: { ProcessPositionUpdate(); // Issue a new request if needed RequestPositionUpdates(); break; } // The data class used was not supported case KErrArgument: .... } } After a position update notification has been received, the client application must re-issue the request if it wishes to obtain further updates. Cleaning up and tearing down Requests issued with RPositioner and RPositionServer can be cancelled using their CancelRequest() methods. Subsession and session handles to the Location Server have to be closed by calling RPositioner::Close() and RPositionServer::Close() respectively. CLbsPositionRequestor::~CLbsPositionRequestor { ... //cancelling pending requests // Cancel() calls DoCancel() if the object is active // closing sessions iPositioner.Close(); iPosServer.Close(); ... } Working with landmarks The Landmarks API offers features to access, search and update landmarks databases residing locally on the device or available online. The CPosLandMarksDatabase class provides APIs for creating, opening and closing databases as well as receiving notification of database management events. Once a database is open, the CPosLandmarkSearch class and associated criteria classes are used to execute a landmark search, and the CPosLandmarkParser and CPosLandmarkEncoder classes can be used to import and export landmarks.
  • 17. 14 Three UI APIs are available to enable user interaction with the landmark information: • CLmkEditorDlg, which provides a dialog for editing landmark data • CLmkCategorySelectorDlg and CLmkLandmarkSelectorDlg, which provide selection dialogs. The data edited with CLmkEditorDlg is automatically saved in the database when the dialog is closed, so this dialog can be employed to allow the user to inspect and edit the content of a new landmark before it is added to the database. Accessing and manipulating databases The CPosLandMarksDatabase class is used to access a landmarks database. The Landmarks Database Management API provides facilities for listing databases as well as creating and deleting databases. Clients can also subscribe to notifications on changes to a landmarks database. void CLandmarkManager::ConstructL() { ... // open the default landmarks database // CPosLandmarkDatabase* iDb (is defined elsewhere); iDb = CPosLandmarkDatabase::OpenL(); InitializeIfNeededL(); ... } Landmarks database operations, such as searching within a large set of landmarks, are potentially time consuming. To prevent such operations blocking the main application, it is recommended that such tasks be broken into smaller sub tasks and run incrementally by assigning an active object to run the task. The Landmark API provides the CPosLmOperation object for such operations, as illustrated in this code used to initialize a landmarks database: void CLandmarkManager::InitializeIfNeededL() { // check if landmarks database needs to be initialized // run the initialization via CPosLmOperation object if necessary if (iDb.IsInitializingNeeded()) { // Create initialize operation // CPosLmOperation* iOperation // TReal32 iProgress (is defined elsewhere) iOperation = iDb.InitializeL(); iOperation->NextStep( iStatus, iProgress ); SetActive(); } } void CLandmarkManager::RunL() { if ( iStatus == KPosLmOperationNotComplete ) {
  • 18. 15 // The operation has not completed. // Use iProgress to indicate progress // Perform the next initialization step iOperation->NextStep( iStatus, iProgress ); SetActive(); } else { // The operation has completed. // check for potential errors here and handle the result } } Operations that normally need to be run incrementally are possible using the ExecuteL() and ExecuteAndDeleteLD() Landmarks API utility methods. Searching landmarks The Landmarks Search API enables searching of a landmarks database. Such searches can be refined by defining names, categories, distance to a location, text values or any combination of these criteria. The user can also refine a search result by applying new search criteria to the cached result. The search is executed incrementally, with a similar execution model as displayed in the code snippet provided in the previous section. Search operation results can be sorted using criteria such as position or category and can be iterated through using the returned CPosLmIterator object. If search results need to be displayed to the user during the search, the display data functionality of the Landmarks Search API has to be used to access the partial result set. The code snippet below searches for landmarks with the word ‘flowers’ in their name. The search is run in one step without displaying a progress dialog or incrementally reporting search results. void CLandmarkManager::ExamplifySearch() { _LIT(KSearchString, "flowers"); ... // Create a search object and provide the CPosLandmarkDatabase // object. CPosLandmarkSearch* search = CPosLandmarkSearch::NewL(*iDb); CleanupStack::PushL(search); // Create the search criteria CPosLmTextCriteria* crit = CPosLmTextCriteria::NewLC(); crit->SetTextL(KSearchString); // Start the search and execute it at once. ExecuteAndDeleteLD(search->StartLandmarkSearchL(*crit)); CleanupStack::PopAndDestroy(crit); // Retrieve an iterator to access the matching landmarks. CPosLmItemIterator* iter = search->MatchIteratorL(); CleanupStack::PushL(iter);
  • 19. 16 // Iterate the search matches. TPosLmItemId lmID; while ((lmID = iter->NextL()) != KPosLmNullItemId) { CPosLandmark* lm = iDb->ReadLandmarkLC(lmID); // Do something with the landmark information ... CleanupStack::PopAndDestroy(lm); } // delete iterator and search objects CleanupStack::PopAndDestroy(2, search); ... } Importing and exporting landmarks The S60 platform provides for exchanging landmark data between users or applications on different devices or computers using the LMX format. The CPosLandmarkEncoder and CPosLandmarkParser classes are used to export and import landmarks. The CPosLandmarkEncoder class either exports all landmarks or a subset based on an ID array of the landmarks to be exported that are passed to the instantiated export object. If any of the landmarks in the ID array are not present in the database, the entire export operation will fail. The code below shows how to export landmarks to a file using the CPosLandmarkDatabase() method. In this example the incremental operations are executed synchronously. void CLandmarkManager::ExportSelectedLandmarksL( RArray<TPosLmItemId>& aSelectedLandmarks) { LIT( KExportFilePath, "c:eposLmExport.lmx" ); // Mime type of landmarks exchange format _LIT8( KPosMimeTypeLandmarkCollectionXml, "application/vnd.nokia.landmarkcollection+xml" ); // Create the encoder to be used for exporting landmarks CPosLandmarkEncoder* encoder = CPosLandmarkEncoder::NewL( KPosMimeTypeLandmarkCollectionXml ); CleanupStack::PushL( encoder ); // Point out the file to export landmark data to encoder->SetOutputFileL( KExportFilePath ); // Execute the operation in one batch // Note: There must be landmarks for specified // IDs in the database,otherwise operation
  • 20. 17 // will fail with KErrNotFound ExecuteAndDeleteLD( iDb->ExportLandmarksL(*encoder, aSelectedLandmarks, CPosLandmarkDatabase::EIncludeCategories ) ); // Finalize encoding to complete export ExecuteAndDeleteLD( encoder->FinalizeEncodingL() ); CleanupStack::PopAndDestroy( encoder ); } The import of landmark data is performed using the CPosLandmarkParser class. Imports can be for all the landmarks in the source or for a subset defined by passing an array. The code below imports landmarks from a file using the CPosLandmarkDatabase() method. void CLandmarkManager::ImportLandmarksL( const TDesC& aImportFilePath ) { // Mime type of landmarks exchange format _LIT8( KPosMimeTypeLandmarkCollectionXml, "application/vnd.nokia.landmarkcollection+xml"); // Create the parser to be used for importing landmarks CPosLandmarkParser* parser = CPosLandmarkParser::NewL( KPosMimeTypeLandmarkCollectionXml ); CleanupStack::PushL( parser ); // Point out the file to import landmark data from parser->SetInputFileL( aImportFilePath ); CPosLmOperation* op = iDb->ImportLandmarksL(*parser, CPosLandmarkDatabase::EDefaultOptions ); CleanupStack::PushL( op ); // Execute the operation in one batch op->ExecuteL(); // Fetch the landmark iterator of imported landmark IDs CPosLmItemIterator* iter = iDb->ImportedLandmarksIteratorL( op ); CleanupStack::PushL( iter ); // Fetch imported landmark data using this iterator // Iterate the search matches. TPosLmItemId lmID; while ((lmID = iter->NextL()) != KPosLmNullItemId) { CPosLandmark* lm = iDb->ReadLandmarkLC(lmID); // Do something with the landmark information ...
  • 21. 18 CleanupStack::PopAndDestroy(lm); } // Cleanup CleanupStack::PopAndDestroy( iter ); CleanupStack::PopAndDestroy( op ); CleanupStack::PopAndDestroy( parser ); } As with other landmark operations, exports and imports can be run incrementally. Viewing or editing landmarks Landmarks can be viewed or edited using the Landmarks UI Add/Edit API, which also provides features such as the option to send a landmark or view its location on a map (if a suitable mapping application, such as Nokia Maps, is present on the device). Using the viewer or editor requires the definition of a landmark to work with, either by creating a new one or using one defined by a search result. The dialog is then launched in either viewer or editor mode. Figure 4: The Landmarks Add/Edit UI enables landmarks to be managed by the user The code below launches a landmark viewer dialog for an existing landmark. void CMyLmUiAppView::LaunchLmkViewerWithLmkIdL(TLmkItemIdDbCombiInfo almItem) { //extract the database handle. CPosLandmarkDatabase* db =almItem.GetLmDb(); //extract the seleted landmarks item id TPosLmItemId itemId = almItem.GetItemId(); CLmkEditorDlg::TLmkEditorParams editParams; //set to make visible all the fields in viewer. editParams.iAttributes = CLmkEditorDlg::ELmkAll; //set to launch viewer editParams.iEditorMode = CLmkEditorDlg::ELmkViewer;
  • 22. 19 CLmkEditorDlg *dlg = CLmkEditorDlg::NewL(*db,itemIdeditParams); // set Mop parent dlg->SetMopParent(this); dlg->ExecuteLD() } Selecting landmarks The Landmarks UI Selector API provides a mechanism to enable users to select landmarks or categories from a list. Figure 5: The Landmarks UI Selector API enables the user to choose landmarks or landmark categories Here is a simple code snippet that launches a dialog allowing a user to select multiple landmarks. void CMyLmUiAppView::LaunchLandmarksMultipleSelectorL() { CLmkLandmarkSelectorDlg* lmkSelectDlg = CLmkLandmarkSelectorDlg::NewL(); lmkSelectDlg->SetMopParent(this); RArray<TLmkItemIdCombiInfo> selItemArray; TInt retVal = lmkSelectDlg->ExecuteLD( selItemArray ); // Use selItemArray to get the IDs of the returned landmarks… // and a handle to the database they reside at } Working with other features There is one final feature of the location services: the BLID Application Satellite Info API. This API allows information on the GPS satellites visible to the GPS hardware to be displayed.
  • 23. 20 Figure 6: In S60 3rd Edition, Feature Pack 2 and later, the BLID Application Satellite Info API offers two views of satellite information Other S60 platform runtimes This booklet has concentrated on developing location-aware applications using Symbian C++; however, this is not the only option. Java technology and Python offer developers location APIs in S60 3rd Edition and later. Starting with S60 5th Edition, web widgets and Flash Lite applications gain location APIs. These APIs are introduced in this section. Java technology The S60 platform offers a comprehensive set of Java Micro Edition (Java ME) APIs. Since the introduction of S60 3rd Edition, these have included the Location API for J2ME (JSR-179). This API provides methods for determining the current location, as well as creating and accessing landmark information. A generalized view of the API is shown in Figure 7. LocationProvider LocationListener Figure 7: The architecture of the Location API for Java ME
  • 24. 21 Retrieving a device’s location involves getting an instance of the LocationProvider object and using this to retrieve location information. The example code below shows how this is done. Note that Criteria is set to require the location fix to be accurate within 500 meters and that a timeout on the retrieval of location data has been set at 60 seconds. public void checkLocation() throws Exception { String string; Location l; LocationProvider lp; Coordinates c; Criteria cr= new Criteria(); cr.setHorizontalAccuracy(500); lp= LocationProvider.getInstance(cr); l = lp.getLocation(60); c = l.getQualifiedCoordinates(); if(c != null ) { // Use coordinate information double lat = c.getLatitude(); double lon = c.getLongitude(); string = "nLatitude : " + lat + "nLongitude : " + lon; } else { string ="Location API failed"; } midlet.displayString(string); } Applications created using JSR-179 have access to features similar to those offered by the MLF. As such, Java technology offers an entirely suitable alternative to Symbian C++ for the creation of sophisticated location-aware applications. Web Runtime With the introduction of S60 5th Edition, WRT has been given access to S60 location and landmarks services through a JavaScript binding to S60 Platform Services. This enables developers to perform such operations as acquiring a location, tracing location updates and making location-based calculations, as well as searching and modifying landmark databases. To obtain a device’s location, JavaScript code needs to declare a service object and then get the required service to that object. There are several services offered by the S60 Platform Services binding; others include access to device data such as Contacts and Calendar records. The service object for location information is Service.Location of the type ILocation. Once the object has been created, location information is obtained using the GetLocation() function. Before the function is used, however, an object for criteria is required. These criteria enable the control of the information returned. For example, by setting PartialUpdates to False it is possible to force the request to return a complete set of basic location details. This setting prevents incomplete information being returned if, for example, a built-in GPS had not acquired a reliable fix when the request was initiated. This code snippet shows how a simple widget uses these features to display a device’s latitude and longitude, as shown in Figure 8. Note, however, that this code does not include appropriate error checking.
  • 25. 22 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>My Location Aware Widget</title> <script type="text/javascript"> window.onload = function() { var serviceObject = device.getServiceObject("Service.Location", "ILocation"); var criteria = new Object(); var result = serviceObject.ILocation.GetLocation(criteria); var latitude = result.ReturnValue.Latitude; var longitude = result.ReturnValue.Longitude; alert('Latitude= ' + latitude + 'nLongitude= ' + longitude); }; </script> </head> <body> </body> </html> In addition to longitude and latitude, the variable returned from GetLocation() can provide altitude, satellite, speed, course and heading data. The actual information provided depends on the positioning technology in use on the device, for example, if network positioning is used altitude would not be included in the result. It is also possible to get location information asynchronously using a callback extension to GetLocation(). Figure 8: Location information displayed in an example widget running in the S60 5th Edition emulator
  • 26. 23 With the introduction of S60 Platform Services support to WRT, web developers can now create location-based applications for S60 devices and offer features that were previously achievable in Symbian C++ and Java applications only. Flash Lite With the introduction of S60 5th Edition, Flash Lite developers have access to location and landmark services through an ActionScript binding to the S60 Platform Services. This feature enables Flash Lite developers to perform such operations as acquiring a location, tracing location updates and making location-based calculations as well as searching and modifying landmark databases. To use these features the ActionScript code needs to create a variable to hold a specific service object, such as the location service. Once this is done another variable can be set to a specific attribute of the service, such as location, as shown in the following code: var so = new Service("Service.Location", "ILocation"); var location = so.GetLocation(); The variable returned from GetLocation() can provide longitude, latitude, altitude, satellite, speed, course and heading data. With the introduction of S60 Platform Services support to Flash Lite, developers can now create location-based applications for S60 devices and offer features that were previously achievable in Symbian C++ and Java applications only. Python for S60 Python for S60 offers the ease and familiarity of the Python language to S60 application developers. It is currently available as a plug-in for the S60 SDKs and Nokia devices based on S60 3rd Edition or later. The plug-ins are obtained from the Python for S60 project hosted on SourceForge (sourceforge.net/project/showfiles.php?group_id=154155). Extensions provided in Python for S60 offer developers access to a wide range of native Symbian OS and S60 features, including presentation using the native S60 UI. Support for location-aware applications is provided through the dynamically loaded extension modules, location and position. The location module provides basic information from a mobile network, such as country code and Cell ID. Location applications using this module would need to look up location information based on Cell ID. The position module provides developers with access to location information from an external GPS, and for S60 3rd Edition, Feature Pack 2 or later devices, an internal GPS where available. Python for S60 does not offer the ability to create or use landmarks stored in an S60 device. While Python for S60 is most commonly used for application prototyping, it offers developers a practical alternative to Symbian C++ and the Java language for location-aware applications.
  • 27. 24 Building a complete application While the S60 platform provides you with services for determining location and storing landmarks, alone these are rarely sufficient to build a user friendly location-based application. So whether you are building a fully fledged navigation solution or simply updating a user’s location to a social networking web community, location needs to be given context. Context options Context will generally come from one of the following sources: mapping information, navigation services, point of interest information, user-generated content and advertising. Mapping information The conventional context for a location is found on a map. However, the options for mapping information are numerous. The two basic options are raster or vector-based. Raster maps allow you to use the content you would see on conventional printed maps directly. Raster maps, however, have the significant drawback of generally requiring more data to provide similar information to vector maps. They also offer few options for displaying summary information in overviews and zooming into details could result in pixilation, unless different raster images are available for various zoom levels. By contrast, vector maps generally require less data storage or transmission, and can offer summary and detailed views from the same data set. In addition, vector maps can offer the option to provide either 2D or 3D views. Figure 9: Raster maps are used in ViewRanger (www.viewranger.com) and vector maps are used in Nokia Maps Navigation services In many instances, the user of a location-aware application will want to travel from their current location to a place they have identified with the application. To facilitate the user’s travel an application can offer a navigation service. Such a service would allow the user to define criteria for the route they want to select, for example, specifying whether they are using a motor vehicle or walking and whether they wish to avoid certain transportation network features, such as toll roads or motorways.
  • 28. 25 Figure 10: Nokia Maps offers route planning and voice guided navigation of a route The presentation of a route can be achieved in several ways: it may be highlighted on a map with the user tracking their progress by comparing the route to their current location through to offering directions on screen, possibly supplemented with voice commands. Point of interest information While a map provides a user with context to their location and, depending on the map used, basic information on major features in the surrounding area, it rarely provides specific point of interest (POI) information. So while a map can tell your user they are on a particular street, it does not provide them with any information on the attractions or services offered on that street. Figure 11: Nokia Maps showing POIs in the vicinity of Earl’s Court, London In addition, your user may wish to answer specific questions about their surroundings, such as ‘Where is the nearest restaurant?’ To do this, access is required to a database of POIs tagged with descriptive information.
  • 29. 26 User-generated content While user-generated content alone will rarely provide, at least initially, a full context to locations, it is an engaging way of involving users in your application. User-generated content can cover a range of media such as still images, video and sound recording, and textual information describing the features of a location. Figure 12: GyPSii (www.gypsii.com) enables its users to create content tagged with the location that the content is from Advertising While advertising alone may not provide the sort of information your users would find palatable, it can be used with other context information to add value to your application and generate additional revenue. To work effectively, the use of advertising needs to be balanced with free or purchased content and could benefit from targeting specific user interests and needs. Figure 13: GyPSii (www.gypsii.com) incorporates location-based advertising unobtrusively within user-generated content
  • 30. 27 Ultimately, your final application will probably combine several of these context types. For example, a social networking application may allow someone to find a restaurant which is conveniently located for a group of friends to travel to, then user-generated content could provide independent information on the quality of the restaurant or images of its facade, advertising content could offer a discount voucher and finally a navigation service could guide the friends to the restaurant. Sourcing context data The first step in adding context to your application is determining the needs of your users. From this you can determine the nature and level of information required to provide an appropriate context. The provision of some context may be inherent within the application. Information on the location of friends and family would be inherently available in an application designed to allow the user to track those people. User-generated content requires two enablers: a method for users to upload location-tagged information and a mechanism to store and retrieve this information. Location-based advertising, at least for now, would require a similar application-specific infrastructure. For the remaining context information, maps, navigation services and POIs, there are options for using an external provider. In fact, the sheer quantity of data and the transient nature of location information, such as POIs, make the use of an external service almost the only practical option. Even so, there are still several options to be considered, including: • Using an on-device, third-party map data and visualization application. In this case your application would rely on another application to provide the map visualization and other related services to the end user. Where available, this approach removes the burden of tasks such as map visualization and routing from your code. In addition, it can leverage that application’s map information download capabilities and use data the user has already downloaded to their device. It also means map information will be presented in a way that is familiar to the device user. The disadvantages of this approach are that you will have to limit your mapping capabilities to those offered by the application and such an application may not be available on all devices, or may offer different features on different licensees’ devices. Nokia Maps (www.nokia.com/maps) provides this capability to the built-in applications on Nokia S60 devices. • Using a web-based GIS service. This is a popular approach to building location-aware applications that relies on a service provider that offers mapping, POIs, routing and geocoding as a web service. This approach removes the burden of basic map data manipulation from your application, but your application may have to provide the presentation UI for any visualization or service, such as navigation. The licensing arrangements may also limit the ability to cache data, or the format of data supplied by the provider may result in higher network usage compared to other methods. Examples of companies offering this service include Google (code.google.com), deCarta (www.decarta.com) and MapTP (developer.navteq.com/site/global/zones/ms/index.jsp). • Embedding a third-party GIS engine. This approach is similar to the using a web-based GIS service; however, an on-device engine is used to perform the basic data acquisition and presentation tasks, hiding much of the complexity away from your application. The principal advantages of this approach
  • 31. 28 are its flexibility compared to using a web-based GIS Service. it also guarantees that the same visualization and service options are available on all devices and you are in control of the UI and data presentation. At the time of writing, there are two products available for the S60 platform: AtlasCt Mobile Map API for J2ME (www.atlasct.com) and Carmenta Mobile engine for Symbian C++ (www.carmenta.com). • Building your own engine. This is the most complex solution as it involves using raw data from map data providers, such as TeleAtlas (www.teleatlas.com), Navteq (www.navteq.com), and regional or local providers, and creating an engine to manipulate that data to create imagery, POI, routing and other services. This approach is likely to be most useful for specialized applications, such as those using topographic data. An architectural view of the various options is given in Figure 14. Figure 14: The options for implementing geospatial context information in your application Context data storage and access Having determined how geospatial information is to be sourced, you need to make one further decision: how the user will access this information. Will the information be provided as a fixed data set loaded and stored on the user’s device or will the data be delivered over-the-air when it is needed? Providing the user with a fixed data set on their device means that they incur no additional costs for accessing the information, but this information will almost certainly become out of date and may limit coverage to the specific areas loaded at the time of purchase. Accessing the data live allows the user to have the most up-to-date information and extend data to new geographical areas, but means they may incur costs for data traffic on their mobile network. Generally, the most appropriate solution is a hybrid. This may involve accessing all information over-the-air initially but then caching it on the device or offering some elements as fixed data, such as providing a set of maps on-device but then accessing POI information over the network.
  • 32. 29 It is also possible that the selection of a particular geospatial service provider may, either technically or contractually, limit the access and storage options. Development and testing tools S60 applications are developed on a PC using an S60 SDK in conjunction with Carbide.c++, Microsoft Visual Studio with Carbide.vs or using command line tools. Once an application has been coded it is initially compiled for an S60 emulator. Using an S60 emulator, the application can be tested on a PC. Testing is an essential part of any application development project. Running an application with a representative sample of data is a straightforward, if sometimes non-trivial, task for most applications. As location-aware applications rely on the physical location of a device, how is testing possible without either severely restricting the test data set or incurring a significant investment in S60 devices and travel? The answer is simple. Positioning simulation tools are provided in the S60 SDK emulators and for Nokia S60 devices to simulate location and route information through the Simulation PSY. Using locations (a single point saved as a National Marine Electronics Association [NMEA] format file) and routes (saved as Simulated Movement Format [SPS] format files), the Simulation PSY provides data for testing an application. Creating simulated location data The first step in using the positioning simulation tools is creating suitable data. Here you have two options: recording live data or creating entirely artificial data sets. Test data from the real world The advantage of using test data captured from the real world is that it can include the typical inaccuracies that a user would encounter in using your application. To do this, you should collect data in the NMEA format and then ensure that the file is saved with the extension .nme. There are several ways to gather NMEA-dumps. Some GPS receivers may contain the functionality to trace data. There are also a couple of methods, with software contributed by the developer community, documented on the Forum Nokia Wiki: the article ‘NMEA (GPS) Location Viewer’ (wiki.forum.nokia.com/index.php/NMEA_(GPS)_Location_Viewer) provides a Python for S60 script that can be used to log NMEA data, while ‘NMEAXmit - a NMEA dumper for S60 3rd Edition’ (wiki.forum.nokia.com/index.php/NMEAXmit_- _a_NMEA_dumper_for_S60_3rd_Edition) provides a Symbian C++ application able to dump NMEA data to a memory card or send it over a Bluetooth connection. Using the positioning simulation route generator The S60 3rd Edition or later emulators include the Route utility. This allows locations and routes to be created manually. Using the editor in the Route utility, as shown in Figure 15, routes can be created by entering coordinates or by drawing a route in the plot window. A map can also be imported to provide real world context to a location or route.
  • 33. 30 Figure 15: The Route utility allows locations and routes to be created Once a location or route has been saved, it can be utilized by the application running in the emulator or on a device. Using the positioning simulation tool for testing Once you have your test data, the positioning simulation tool provides the mechanism by which you make the data available to your application, using the Simulation PSY. The Simulation PSY and its configurator are included in the S60 SDKs; they are not on S60 devices by default. For devices, the tool consists of two SIS files (SimulationPsy_ARMV5.sis [the PSY] and SimPsyConfigurator.sis [the configurator]) that are provided in the SDK in the epoc32S60toolsSimPSYConfigurator folder. Note: The SIS files in the early S60 3rd Edition SDKs have expired certificates, so it is recommended to use the files from the latest S60 SDK. Alternatively, the necessary files can be downloaded from the Forum Nokia Wiki article, ‘S60 Platform: Positioning Simulation Tool’ (www.forum.nokia.com/info/sw.nokia.com/id/edf2e7be-223d-4b50-af98- 87e0cbe5d186/S60_3rd_Edition_Positioning_Simulation_Tool.html). In addition, at the time of writing, the application installs on Nokia S60 devices only. In the S60 emulator, the Simulation PSY can be launched from the landmarks application, as shown in Figure 16, which is found in the Tools folder. On a device, the configurator can be launched from the GPS data application, which is found either in the Tools or GPS folder. In the appropriate application, select Options > Positioning Settings. (You can also access Positioning Settings from the Settings application, usually found in the main menu or Tools folder, by choosing General > Positioning.) In the Positioning screen, select Positioning methods. In the Positioning methods screen the Simulation option will be shown (on the emulator this is the only option). Now select Options > Settings and the SimPsyConfigurator screen will allow a NMEA or SPS file to be selected. Three files are supplied with the tool. Once a simulation file has been selected, its position information will be made available for use in your application.
  • 34. 31 Figure 16: The steps in selecting a file for position or route simulation on an S60 emulator To make your own data sets available to the Simulation PSY configurator for the S60 emulator, store your files in the folder epoc32releasewinscwudebzsystemdata. When working on a device, install them in the systemdata folder on the drive on which you installed the positioning simulation tool. The NMEAXmit application (mentioned in the ‘Test data from the real world’ section) can save data in the correct location so that it’s accessible to the simulation tool. On a device, if your application offers the user the ability to select the positioning method, then this can be used to select the Simulation PSY. If your application simply connects to the default PSY, then you should disable all the positioning methods except the Simulation PSY to make the data available to your application. You can also explicitly connect to the Simulation PSY using the code outlined in the ‘Opening a location requestor handle’ section. Getting to market The goal of most development projects is distribution of the resulting applications to as many users as possible. Fortunately, there is a wide range of distribution channels available to developers of S60 applications. Independent channels The channels easiest to enter are those that offer applications over the Internet. Channels such as Handango (www.handango.com), GetJar (www.getjar.com) and Handmark (www.handmark.com) offer developers a self-service mechanism; after creating an account, developers can post applications directly to the site’s catalogue. Some Internet-based channels, such as Nokia Software Market (www.softwaremarket.nokia.com), have restrictions on the applications that can be posted. These restrictions include requiring applications to be Symbian Signed or Java Verified. In addition, these sites may perform independent tests to ensure an application works correctly on the supported devices before applications are made available for purchase. An interesting new option for content and application distribution is MOSH. MOSH is a user- defined channel for the distribution of mobile content, allowing all developers (regardless of content type) to distribute to a global market. As MOSH is a community site, it allows developers to connect easily with both the mass market and niche user communities worldwide. For more information visit the MOSH site (mosh.nokia.com).
  • 35. 32 Mobile network operators Operator channels also offer good outlets for applications, especially for applications that are relevant to a particular geographical market, but these channels tend to place applications into their portfolio only after a vetting process. System integrators For services and applications targeted at enterprise use, large system integrators can serve as a channel to target enterprises on a significant scale. Nokia for Business (www.nokiaforbusiness.com) is a channel program designed for application developers to target large system integrators and value-added resellers. Device manufacturers Device manufacturers are becoming increasingly aware of the importance of services and applications and their role in creating value for the consumer. Nokia Download! is an integrated channel that enables developers to deploy their applications and services via an on- device application catalogue. For more information on Nokia-specific channels visit www.forum.nokia.com/main/go_to_market/nokia_channels.html. More information on market channels is provided in the Go to Market section of the Forum Nokia site (www.forum.nokia.com/main/go_to_market) and the Developer section of the Nokia site (www.nokia.com/developer). In addition, the Symbian Press booklet Getting to Market, which can be found on the Symbian Press web site (developer.symbian.com/booklets), provides a handy guide to finding a route to commercial success. Getting further assistance The Forum Nokia web site (www.forum.nokia.com) provides access to a vast range of technical resources designed to help you make the most of the opportunities offered by the S60 platform. For specific information on location-based services there is a dedicated section within Forum Nokia (www.forum.nokia.com/lbs). The community of S60 developers, along with Nokia experts, also actively contributes to providing developers with support through the Forum Nokia Developer Discussion Boards (discussion.forum.nokia.com) and the Forum Nokia Wiki (wiki.forum.nokia.com). Each of these Forum Nokia resources has its own dedicated location-based applications section. For situations that call for immediate support and issues not covered by the discussion boards or wiki, Forum Nokia offers developers fee-based technical support. Developers can purchase support on a case-by-case basis or buy a five-case package or an annual subscription. For support throughout the development of a mobile application, the Forum Nokia Technical Consultancy service is available to work closely with developers at every level and stage of the project. For more information on professional support, visit the Technical Services section of the Forum Nokia site (www.forum.nokia.com/support). Forum Nokia technical support also offers developers the opportunity to take advantage of the S60 API Partnering program. This program allows developers to use undocumented APIs in various S60 devices. To request an API, a developer purchases a Partnering API Request from the Forum Nokia e-store and submits a support request detailing the API or functionality required. Symbian also provides information for developers creating location-aware applications. For documentation, discussion forums and a wiki about Symbian OS development, visit the Symbian Developer Network site (developer.symbian.com).
  • 36. Conclusion The S60 platform offers you the ability to access location information easily and conveniently from within your application. Using this information and combining it with geospatial information provided by your application users, data providers or advertisers enables you to offer your users a rich and enticing location-aware experience. This booklet has provided you with background information on the market for location-aware applications, the basics of location estimation technology, an introduction to the MLF and the APIs available to use it, an overview of the support for location in other S60 runtimes, information on the testing tools available, a guide to the additional geospatial data that can provide context to a location and pointers to selling your application and getting further assistance. It is now up to you to find the right way to add location-awareness to your application and, no doubt, add to the range of exciting and engaging location-aware applications for S60 devices.
  • 37. Developer resources Symbian Developer Network developer.symbian.com Symbian Developer Network Newsletter developer.symbian.com/register Community web sites Forum Nokia forum.nokia.com MOTODEV developer.motorola.com Samsung Mobile Innovator innovator.samsungmobile.com
  • 38. New from Common Design Patterns for Symbian OS: The Foundations of Smartphone Software Common Design Patterns for Symbian OS introduces the common design patterns used to implement a variety of applications and services on Symbian OS. The book describes patterns based on the architectural elements of Symbian OS and discusses how patterns suited for desktop software must be adapted or even avoided on a mobile platform. Multimedia on Symbian OS: Inside the Convergence Device Combining the insights and experience of subject experts within Symbian and the third-party developer community, this book will be an invaluable reference for anyone working with multimedia on Symbian OS. The authors provide details of the native C++ APIs for accessing camera, video, audio, image manipulation and radio tuner functionality, and discuss best practice, tips and tricks. Symbian Press: developer.symbian.com/books
  • 39. from Developing Software for Symbian OS, Second Edition This second edition of Developing Software for Symbian OS helps software developers new to Symbian OS to create smartphone applications. The original book has been updated for Symbian OS v9 and now includes a new chapter on application signing and platform security, and updates throughout for Symbian OS v9 and changes to the development environment. Quick Recipes on Symbian OS This book aims to make it easier to develop applications by describing a number of common programming tasks and providing clear explanations of how to complete them. The recipes are divided by technology, including graphics, multimedia, location-based services, networking, telephony, connectivity and messaging. Full sample code is available for download, so it can be used as a starting point in your own projects.
  • 40. from For all Symbian C++ developers: Symbian OS Communications Programming, 2nd Edition by Iain Campbell S60 Programming - A Tutorial Guide by Coulton & Edwards Symbian OS Explained by Jo Stichbury Symbian OS Internals by Jane Sales Symbian OS Platform Security by Craig Heath Smartphone Operating System Concepts with Symbian OS by Mike Jipping Accredited Symbian Developer Primer by Jo Stichbury & Mark Jacobs
  • 41. from Published Booklets A Guide to P.I.P.S. Carbide.c++ v1.3 Coding Standards Coding Tips Coverity Prevent on Symbian OS Data Sharing Tips Essential S60 - Developers’ Guide Essential UIQ - Getting Started Getting Started Getting to Market Java ME on Symbian OS Localization .NET Development on S60 Performance Tips Platform Security for all Quick Recipes Taster Translated Booklets Chinese Russian Japanese Persian Korean Italian Spanish
  • 44. Essential S60 Creating Location- Aware Applications Why? What? Where? How? Adding location-awareness to S60 applications offers significant possibilities for extending existing applications or creating new ones. This Essential S60 booklet gives background information about positioning technology and location-aware applications, and also provides an introduction to the S60 APIs for developers using Symbian C++, Java ME, Web Runtime or Flash Lite. Creating Location-Aware Applications is part of the Essential S60 series, designed to provide information in a handy format to S60 developers. Symbian Press Symbian Press publishes books designed to communicate authoritative, timely, relevant and practical information about Symbian OS and related technologies. Information about the Symbian Press series can be found at developer.symbian.com/books