Symbian^3 Product Developer Library > Symbian Guide > Location Based Services (LBS) Guide >

LBS Architecture Overview

This document describes the major components and interfaces of the Symbian platform Location Based Services (LBS) subsystem. It is intended to give device creators an appreciation of the LBS subsystem architecture. It also provides links to other documentation that provides more detailed information about the LBS components and APIs.

Contents

Introduction

This document describes the major components and interfaces of the Symbian platform Location Based Services (LBS) subsystem. It is intended to give device creators an appreciation of the LBS subsystem architecture and to provide links to other documentation that provides more detailed information about the LBS components and APIs.

The target audience for this document is device creators who need to integrate the LBS subsystem into hardware. Application developers who want a greater appreciation of the architecture of the LBS subsystem may also find it of interest.

Background

Location Based Services offer application developers and network operators the opportunity to provide mobile users with a range of new services. Existing applications can also be enhanced to add extra value. Examples of services include location stamping of photographs and memos, finding nearby services and facilities, navigation, and the ability for remote parties to discover a user's whereabouts.

The Symbian platform LBS subsystem provides the infrastructure to enable applications to obtain the location of a mobile device. Applications may be installed on the mobile device or they may be network-based services.

To obtain its position, a mobile device must use a positioning technology. There are several different types of positioning technology:

  • Satellite positioning

    The Global Positioning System (GPS) is the most widely used satellite positioning system and uses a constellation of satellites in orbit around the Earth. Hardware inside the mobile device (or external hardware connected to the device) receives the satellite signals. The signals are used to calculate the mobile device's position. Satellite positioning typically provides a greater position accuracy than network positioning.

    LBS on the Symbian platform provides the interfaces for you to develop ECom plug-ins to connect the LBS subsystem to GPS hardware. The Symbian platform contains an ECom plug-in to connect the LBS subsystem to external GPS hardware by using Bluetooth.

  • Network positioning

    The telecommunications network to which the mobile device is connected can usually return an approximate position fix to the device. The position that can be delivered by network positioning is typically less accurate than one returned by satellite positioning. In many situations a network position can be returned more quickly than one calculated by satellite positioning.

    LBS on the Symbian platform provides the interfaces for you to develop an ECom plug-in to connect the LBS subsystem to a network. An ECom plug-in that uses the OMA SUPL v1.0 standard is provided with the Symbian platform.

  • Other positioning technologies

    The LBS subsystem can be extended to support other positioning technologies (such as WLAN positioning).

    You can use the generic Positioning Plug-in API to write ECom plug-ins to integrate with positioning hardware.

How applications use the LBS subsystem

There are three main ways that applications and services use the LBS subsystem:

  1. An installed application wants to use the device's location.

    The application may request the device's location for itself or on behalf of another application or process. The LBS subsystem obtains the device's location and returns it to the application.

    You can use the Location Acquisition API to obtain the device's location. The API provides the same functions to obtain a device's location regardless of the underlying positioning technology used to obtain the position. Hiding the underlying positioning technology behind a generic API in this way means that applications are protected from future changes and advances in positioning technology.

    In 3GPP terminology a request by the mobile device for its own location is known as an MO-LR Self Locate. MO-LR means Mobile Originated Location Request.

  2. An installed application wants to send the location of the mobile device to a contact (phone number) or URL over the network.

    You can use the Transmit to Third Party API to send the user's location to a contact or service.

    In 3GPP terminology this type of request is known as an MO-LR Transmit to Third Party. This is sometimes abbreviated to X3P in the Symbian platform LBS documentation.

  3. A network-based service requests the location of the mobile device.

    A network-based service can request the location of a mobile device by sending a request to the device over the network. The request typically consists of two parts: a privacy request and a location request. The privacy request asks for permission to obtain the position of the mobile device. If this permission is granted by the device user the location request is processed and the mobile device's position is returned to the network-based service.

    One important class of network-based service requests is an emergency services location request. These services obtain the location of a mobile device when the device user makes a call to the emergency services. Emergency services location requests are prioritised by the LBS subsystem.

    In 3GPP terminology requests from the network are known as MT-LR and Emergency MT-LR. MT-LR means Mobile Terminated Location Request.

Application developers who want to get started writing location enabled applications may want to go directly to the Location Acquisition API documentation which describes how to use the API.

LBS components

This section gives an overview of the components of the LBS subsystem.

The LBS subsystem is organised into frameworks and components as shown in figure 1. It shows a combination of both core LBS components and those that extend the capabilities of LBS (in grey). The core components are those shown within the Location Based Services component (but note that the PSYs in the Location Server Framework are optional components). The optional components are the PSYs in Data Source Modules and the Protocol Modules in Network Protocol Modules.

Note: figure 1 does not show all of the libraries that are part of the LBS subsystem.

You must include all of the core components in a device to support Location Based Services. Optional components can be included if you require the feature that the component provides.

Figure 1. Figure 1. LBS subsystem components.

The core components of the subsystem are as follows:

  • Location Server Framework

  • Positioning Framework

  • Network Request Handler

  • Network Gateway

  • Administration Services

  • Logging Service

The optional components of the LBS subsystem are as follows:

  • The components of the Data Source Modules collection, which are Positioning Modules (PSYs):

    • The Default PSY

    • The Bluetooth GPS PSY

    • The Simulation PSY

    • The GPS/A-GPS PSY

    • The Network PSY

    Note: The GPS/A-GPS PSY and the Network Positioning PSY connect the Location Server to the Positioning Framework. They are shown within the Location Server Framework in figure 1 because of their role in connecting components of the LBS subsystem.

  • The components of the Network Protocol Modules collection:

    • The Privacy Protocol Module

    • The SUPL Protocol Module. (The SUPL Proxy Protocol Module from Symbian^3 onwards)

Location Server Framework

The Location Server Framework receives location requests from installed applications (MO-LR self locate requests). The framework contains a Symbian platform server called the Location Server (eposserver.exe) that processes the location requests.

The Location Server sends requests for location to one or more Positioning Plug-ins (PSYs). A PSY is an ECom plug-in that implements the Positioning Plug-in API (PSY API) to connect the Location Server to positioning technology hardware. A PSY collects and combines location requests from the Location Server and returns position updates when these are required by the Location Server. The Location Server can use more than one PSY simultaneously.

The Location Server can obtain position data in one of three ways:

  • Directly from positioning hardware (or a simulated source of positions) by using one of the pre-built PSYs provided with the Symbian platform.

  • Directly from positioning hardware by using a PSY developed by the device creator.

    You can write your own PSYs to integrate directly with positioning hardware. You could create a PSY to integrate with GPS hardware or WLAN positioning hardware in the mobile device.

  • By using the LBS Positioning Framework with one of the PSYs provided as part of the Symbian platform. There are two PSYs that connect the Location Server to the Positioning Framework:

    • The GPS/A-GPS PSY

      The GPS/A-GPS PSY allows the Location Server to use the Positioning Framework to obtain a GPS position fix with or without the use of A-GPS assistance data from the network. Use of the GPS/A-GPS PSY requires that a device creator develops both an A-GPS Integration Module and a Network Protocol Module.

    • The Network PSY

      The Network PSY allows the Location Server to use the Positioning Framework to obtain a position fix using cell-based positioning. Use of the Network PSY requires that the device creator develops a Network Protocol Module.

See Location Acquisition API documentation for a description of how to use the LBS subsystem to get a location fix.

Positioning Framework

The Positioning Framework contains Location Manager processes. Location Managers are responsible for receiving location requests from the Location Server and the Network Request Handler and for forwarding the requests to components that can obtain a position fix.

A-GPS Location Manager

The A-GPS Location Manager is the process responsible for obtaining A-GPS position fixes. It is responsible for handling location requests from the Network Request Handler. It also receives location requests from the Location Server if the server uses the GPS/A-GPS PSY to process the request.

The A-GPS Location Manager loads a single A-GPS Integration Module (ECom plug-in) when it starts. An A-GPS Integration Module is a component that connects the A-GPS Location Manager to A-GPS positioning hardware. To use the A-GPS Location Manager, a device creator must build their own A-GPS Integration Module since one is not provided with the Symbian platform.

See A-GPS Integration Module for information about the API that you must use to write an A-GPS Integration Module.

Network Location Manager

The Network Location Manager handles location requests from the Location Server if the Network PSY is used by the Location Server to process a location request.

The Network Location Manager sends requests to the Network Gateway where they are forwarded to a network. The network used by the Network Location Manager is controlled by the choice of Network Protocol Module (ECom plug-in) that is loaded by the Network Gateway when it starts. The Network Gateway can load up to two Network Protocol Modules. One Network Protocol Module can be used in the device's home network and another can be used when the device is outside of the home network.

See Network Protocol Module for information about the API that you must use to write a Network Protocol Module.

Location Monitor

The Location Monitor manages previously stored location information. It monitors location updates and network information and builds up a database of location information. It handles requests from the Location Server for previously stored location data.

See Location Monitor for a description of the Location Monitor component.

Network Request Handler

The Network Request Handler has two main functions:

  • Handling requests for location received from the network (emergency services and non-emergency services requests). Requests from network-based services typically consist of two parts:

    1. A privacy request to ask the mobile user for permission to obtain the mobile device's location (or simply notify the user for emergency services requests).

    2. A location request that is processed if the privacy request is accepted.

    Depending on the type of privacy request, a user may be required to verify that the mobile device's location can be sent to the network. The Network Request Handler is responsible for obtaining permission from the user. If permission is granted it works with the A-GPS Location Manager to obtain the device's location.

    The Network Request Handler uses Privacy Notifiers or a Privacy Controller to obtain a response to privacy requests:

    • Privacy Notifiers are used to obtain a privacy response (acceptance or denial of the privacy request) from the mobile user. Emergency privacy requests do not require authorisation from the user although dialogs may be used to inform the user that a location is being sent to the network.

    • A Privacy Controller application can be used to process privacy requests. A Privacy Controller is an application developed by a device creator. The Privacy Controller may use rules to automatically process privacy requests and it may also request user input by using dialogs. The implementation details of a Privacy Controller, such as the implementation of privacy rules are completely under the control of the Privacy Controller developer.

    An administration setting determines whether a Privacy Controller or Privacy Notifiers are used. See LBS Privacy Requests for more information about how privacy requests are handled.

  • Initiating and handling requests to send the mobile device location to a remote party (MO-LR transmit to third party).

    The Network Request Handler Server is responsible for initiating and handling the request to send the location and for the interaction with the A-GPS Location Manager to obtain the location.

    See Sending location to a third party for more information.

Network Gateway

The Network Gateway is the process in the LBS subsystem that interacts with a network. The Network Gateway communicates with the network using a Network Protocol Module ECom plug-in and performs the following functions:

  • Receiving location requests from the network (MT-LR, Emergency MT-LR and NI-LR) and forwarding them to the Network Request Handler

  • Forwarding requests for A-GPS assistance data to the network and receiving responses

  • Forwarding calculated positions to the network

  • Forwarding GPS measurements to the network and receiving the calculated positions (for A-GPS)

  • Forwarding a position to a remote party over the network (MO-LR transmit to third party)

To use the Network Gateway a device creator must develop and configure at least one Network Protocol Module

Administration Services

Administration Services contains two main classes of components:

  • An LBS root process that is responsible for starting all of the other LBS subsystem processes as required and for monitoring their status. You can configure LBS to decide on how to start the root process and the other components of the LBS subsystem.

  • A set of libraries that define APIs for configuring and managing various components of the LBS subsystem. These APIs are described in more detail in the LBS APIs section of this document.

Logging Service

LBS subsystem events are logged by subsystem components using the Logging Service. The Logging Service uses the standard Symbian platform log engine to write LBS log entries. You can use the Logging API to create an application to read information from the log. One example of such an application is one that could show a list of the times of all location requests made by the user.

See LBS logging for more information about using the Logging Service.

Data Source Modules

The Symbian platform includes several PSYs that can be included in a product by a device creator. The PSYs connect the Location Server to sources of position data. The PSYs cannot be used with the deprecated Location Server.

  • The GPS/A-GPS Positioning Module connects the Location Server to the A-GPS Location Manager and is the recommended way of getting a GPS/A-GPS position fix from the LBS subsystem.

  • The Network Positioning Module connects the Location Server to the Network Location Manager. It is the recommended way of getting a cell-based position from the LBS subsystem.

  • The Bluetooth GPS Positioning Module connects the Location Server to an external Bluetooth GPS device. It is the recommended way of getting a position from a Bluetooth GPS device.

  • The Simulation Positioning Module provides the Location Server with simulated position data (which can be read from a file). The Simulation PSY allows application developers to test their location-enabled applications on an emulator or on hardware.

Network Protocol Modules

The Network Gateway must load a Network Protocol Module to connect to a network. You can develop a Network Protocol Module or you can use one of the Protocol Modules provided with the Symbian platform. There are two Network Protocol Modules provided with the Symbian platform:

  • The SUPL Proxy Protocol Module

    The SUPL Protocol Module (SPM) allows the mobile device to act as a SUPL Enabled Terminal (SET) as described in the Open Mobile Alliance Secure User Plane Location (OMA SUPL) architecture. The protocol uses the Application Processor Engine (APE) to request network and AGPS positions. For platforms before Symbian^3 see the SUPL Protocol Module.

  • The Privacy Protocol Module

    The Privacy Protocol Module (PPM) allows the LBS subsystem to receive privacy requests from the device native operating system. The request may originate from the network or from an application installed on the device.

    If the Network Gateway is configured to use the PPM, the LBS subsystem can process only privacy requests received from the device domestic OS (from either the network or from an installed process). Location requests from the network must be handled by some other means. The Privacy Protocol Module cannot be used to handle location requests.

LBS APIs

The following is a list of the APIs provided by the LBS subsystem, together with a brief explanation. It provides a set of links for developers who want to understand how to perform a particular task on the LBS subsystem.

Location Request APIs

API Purpose

Location Acquisition API

Application developers use the Location Acquisition API to obtain the location of the mobile device, to get information about the device's positioning capabilities and the status of its positioning hardware.

Positioning Module APIs

API Purpose

Positioning Plug-in (PSY) API

Use the PSY API to create ECom plug-ins to connect the Location Server to positioning hardware.

Positioning Plug-in (PSY)Information API

The PSY Information API consists of a set of Central Repository keys that a PSY developer must use to register the PSY with the LBS subsystem. The Location Server uses the keys to discover the PSY and read its capabilities.

A-GPS Location Data Source API

Use the API to create an ECom plug-in to connect the LBS subsystem (the A-GPS Manager) to internal A-GPS hardware.

Network Protocol Module APIs

API Purpose

Network Protocol Module API

Use the API to create an ECom plug-in to connect the LBS subsystem to a network via the Network Gateway.

SUPL Push API

Use this API to write ECom plug-ins to send SUPL Push messages to the SUPL Protocol Module.

Network Privacy API

The Privacy Protocol Module can receive privacy requests via this API. A process running in the device domestic OS uses the API to send privacy requests from the network into the LBS subsystem.

Privacy Request API

The Privacy Protocol Module can receive privacy requests via this API. A process running in the device domestic OS uses the API to send privacy requests from installed applications into the LBS subsystem.

Privacy Request APIs

API Purpose

Privacy Controller API

The API allows a device creator to build an application that automatically processes privacy requests, with or without involving the mobile user.

Privacy Notifiers API

The API is used to develop notifiers to send simple privacy notification and verification messages to the mobile user when privacy requests are received.

Privacy Q&N API

This is a deprecated API that is used to send simple privacy notification and verification messages to the mobile user. It is recommended that the Privacy Notifiers API is used instead.

Administration Service APIs

API Purpose

LBS Administration API

The API provides functions to get and set LBS system-wide settings. The settings modify the general behaviour of the LBS subsystem. You can develop an application that uses this API if you want to give device users control over the subsystem behaviour at runtime.

Location Settings API

The API is used to get and set attributes of the PSYs that are loaded by the LBS subsystem. You can create an application that uses this API if you want to give device users visibility of PSY settings and the ability to change some of them.

Integrated GPS Hardware Status API

The API can be used by integrated GPS hardware to notify its status to the LBS subsystem. It can also be used to get the status of the GPS hardware.

Positioning Indicator API

A deprecated API used to get the status of GPS hardware. It is recommended that the Integrated GPS Hardware Status API is used instead.

Quality Profile API

The Quality Profile API is intended for use by components developed by you (such as an A-GPS Integration Module or Network Protocol Module) to obtain LBS quality profile information.

Logging Service APIs

API Purpose

Logging API

A developer can use this API to read LBS events from the LBS event log. It can be used by an application to give the user a view of their LBS activity.

Location Request APIs

API Purpose

Transmit Location API

A developer can use this API to send the mobile device's location across the network to a contact or service.

LBS System Model

The LBS subsystem is a package within the Symbian platform System Model. The System Model is a component deployment view of Symbian platform where each component defines code and configuration information that a device creator can include in a device ROM. Figure 2 shows the collections and components of the LBS System Model. The model is layered, with collections containing groups of related components.

Figure 2. Figure 2. Collections and components of the LBS System Model.

The LBS Integration and Configuration Guide contains information about how to build and configure the components in the LBS subsystem.

The following tables list the executables and libraries that are part of each of the components of the LBS system model.

Location Request Management

Component Component name Component exes/libraries and their purpose

Location Server

lbs_locationserver

  • eposserver.exe is the Location Server.

  • lbsqualityprofileapi.dll contains the Quality Profile API for reading LBS Quality Profiles.

Network Request Handler

lbs_networkrequesthandler

  • lbsnetworkrequesthandler.exe handles privacy and location requests from the network, forwarding them to a Privacy Controller or a Privacy Notifier. It also handles requests to send location to remote parties.

  • lbsprivacycontroller.dll contains the Privacy Controller API for automatically processing privacy requests.

  • lbsprivacyextnotifiers.dll contains the Privacy Notifiers API that allows privacy request information to be passed to Privacy Notifiers.

  • eposprvqnif.dll contains the Privacy Query and Notification (Q&N) API that can be used to create Privacy Notifiers. The API is deprecated and it is recommended that the Privacy Notifiers API is used instead.

  • eposprvtyp.dll contains data types that are used by the Privacy Query and Notification (Q&N) API.

  • lbsx3p.dll contains the Transmit Location API to allow a user to send their location to a remote party over the network.

Location Management

Component Component name Component exes and libraries

A-GPS Location Manager

lbs_agpslocationmanager

lbsgpslocmanager.exe handles GPS location requests from the Network Request Handler and the Location Server. Forwards requests to an A-GPS Integration Module and to the Network Gateway.

Network Location Manager

lbs_networklocationmanager

lbsnetlocmanager.exe handles Network Location Requests from the Location Server and forwards them to the Network Gateway.

Network Gateway

lbs_networkgateway

lbsnetgateway.exe provides connectivity between the LBS subsystem and a network. Loads a Network Protocol Module to implement a particular Location Based Services network protocol.

Location Core

lbs_core

  • lbsloccommon.dll contains common classes and types used in the LBS subsystem.

  • lbs.dll is used by Location Acquisition API client applications. Connects the client to the Location Server eposserver.exe.

  • lbslogger.dll contains the Logging API for applications that need access to LBS event logs.

  • lbsassistancedata.dll contains the Assistance Data API for reading and writing A-GPS assistance data.

  • lbspartnercommon.dll contains classes and types used internally by the LBS subsystem.

  • lbslocdatasource.dll contains the A-GPS Location Data Source API to create an A-GPS Positioning Modules.

  • gpssetclock.dll contains an API that you can use to create your own ECom plug-in to override the default method of setting the mobile device's system time.

  • lbsinternalapi.dll contains APIs used internally by LBS components.

  • lbsnetprotocol.dll contains the Network Protocol Module API used to create Network Protocol Modules.

  • lbsnetinternalapi.dll contains APIs used internally by LBS components.

  • lbsroot.exe is the root LBS process that starts and monitors the other processes of the LBS subsystem.

  • lbsrootapi.dll contains the API by which the LBS root process is notified to start by the Symbian platform. It also contains APIs used by the core components of the LBS subsystem to register themselves with the LBS root process and to

  • lbsadmin.dll contains the API to allows you to build an application for users to control some aspects of LBS subsystem behaviour at runtime.

  • eposmodset.dll contains the Location Settings API, which allows you to modify some properties of PSYs and how the Location Server uses them.

  • eposindicator.dll contains the Integrated GPS Hardware Status API that is used by hardware to update the LBS subsystem with its status. It can also be used to update UI components when the state of GPS hardware changes.

  • eposutils.dll contains utility classes used by the Location Server Framework and the Positioning Framework components.

  • lbslocmonclient.dll is the Location Monitor client interface. Connects the client to the Location Monitor (lbs_locationmonitor).

Location Monitor

lbs_locationmonitor

locationmonitor.exe handles previously stored location requests from the Location Server.

Network Protocol Modules

Component Component name Component exes and libraries

Privacy Protocol Module (PPM)

lbs_privacyprotocolmodule

  • lbsprivacyprotocolmodule.dll contains the Privacy Protocol Module that allows the Network Gateway to receive privacy requests from the device creator's domestic OS.

  • eposnwprv.dll contains the Network Privacy API that allows processes running in the device creator's domestic OS to send requests into the LBS subsystem.

  • lbsprivacyrequest.dll contains the Privacy Request API, an alternative to the Network Privacy API that allows processes running in the device creator's domestic OS to send requests into the LBS subsystem.

SUPL Protocol Module (SPM)

lbs_suplprotocolmodule

  • suplprotocolmodule.dll is the main library of the SUPL Protocol Module.

  • lbshostsettings.dll contains the Host Settings API used to configure the SUPL hosts to which the SPM connects.

  • suplconnectionmanager.dll is the component of the SPM that handles connections with the network.

  • supldevlogger.dll is the logging component used by the SPM to write log messages to the LBS log.

  • lbssuplpush.dll contains an API that allows SUPL Push messages to be sent to the SUPL Protocol Module.

  • suplrrlpasn1.dll contains libraries that contain ASN.1 data structures used for data encoding between the SPM and a SUPL host.

  • suplrrlpprotocol.dll contains the state machine for handling the network protocol.

Data Source Adaptation

Component Component name Component exes and libraries

GPS Data Source Adaptation

lbs_gps_data_source_adaptation

  • epospluginfw.dll contains the Positioning Plug-in API used to create Ecom plug-ins to integrate with positioning hardware.

  • psytester.exe is the application used to test positioning plug-ins.

  • psycrtester.exe is used by psytester.exe to perform capability checks on a PSY.

Data Source Modules

Component Component name Component exes and libraries

Default Positioning Module

lbs_default_positioning_module

eposdefault.dll contains the Default PSY that is used by the Location Server to select other PSYs to service location requests.

Bluetooth GPS Positioning Module

lbs_default_positioning_module

nlabtgpspsy.dll contains the Bluetooth PSY that is used by the Location Server to connect to external Bluetooth GPS hardware.

Simulation Positioning Module

lbs_simulation_positioning_module

epossimulationpsy.dll contains a PSY that contains simulated position fixes to the Location Server. This PSY can be used for testing location based applications.

GPS/A-GPS Positioning Module

lbs_agps_positioning_module

lbsgpsagpspsy.dll contains two PSYs - the A-GPS PSY and the GPS PSY. These two PSYs are used to connect the Location Server to the A-GPS Location Manager.

The A-GPS PSY connects the Location Server to the A-GPS Location Manager, which uses an A-GPS Integration Module to obtain a position fix. The A-GPS PSY configures the Integration Module to use assisted GPS.

The GPS PSY allows the Location Server to use an A-GPS Integration Module to obtain a position fix. The GPS PSY configures the Integration Module to use autonomous GPS.

Network Positioning Module

lbs_network_positioning_module

lbsnetpsy.dll contains a PSY that connects the Location Server to the Network Location Manager so that the Location Server can receive positions calculated using cell-based positioning.

Parent topic: Location Based Services (LBS) Guide
Related concepts
LBS Integration and Configuration Guide

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.