<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-7233BC33-6060-5D6B-A5D2-01135F059337" xml:lang="en"><title>LBS

Architecture Overview</title><shortdesc>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. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F0D7085A-132F-4649-A9C5-E9999670F7DF"><title>Contents</title> <ul>

<li id="GUID-CCE4F772-FB64-583E-A6C8-D4EBEB4AD910"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-BF715542-04CB-53C6-8A99-6D0AA3880A60">Introduction</xref>  </p> </li>

<li id="GUID-B4FA8828-F7D4-5483-891A-D340AA6820E0"><p> <xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-34957EA8-31D3-5885-8E3C-CA5ED0E1984F">Background</xref>  </p> </li>

<li id="GUID-5C815681-10A8-5415-A437-AA41105C4AB1"><p> <xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-BA737C24-B56F-5796-9ECB-3BB1ABB8F179">How applications use the LBS subsystem</xref>  </p> </li>

<li id="GUID-9D0E27EE-66A7-5575-BA20-012916214D40"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-38D6FCCB-C176-5759-B2E6-C6A5891A958B">LBS components</xref>  </p> </li>

<li id="GUID-F36F9547-3D4C-51E6-B480-A9A3A054FE9B"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-73A867D4-4C04-5B77-A117-14058F0C970E">LBS APIs</xref>  </p> </li>

<li id="GUID-82828E4B-ED81-57D7-AABA-2A4629D02856"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-23362766-0CD3-5890-B930-B79C0E4451B8">LBS System Model</xref>  </p> </li>

<li id="GUID-38369D7F-C5EE-592E-A5C8-F47293B4DBE5"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-1DF5EFE0-2717-5150-99A1-B0DE6B91E381">See also</xref>  </p> </li>

</ul> </section>

<section id="GUID-BF715542-04CB-53C6-8A99-6D0AA3880A60"><title>Introduction</title> <p>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. </p> <p>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. </p> </section>

<section id="GUID-34957EA8-31D3-5885-8E3C-CA5ED0E1984F"><title>Background </title> <p>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. </p> <p>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. </p> <p>To obtain

its position, a mobile device must use a <i>positioning technology</i>. There

are several different types of positioning technology: </p> <ul>

<li id="GUID-E188363E-905F-522A-A2DE-D09A42725EC7"><p>Satellite positioning </p> <p>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. </p> <p>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. </p> </li>

<li id="GUID-92C7967E-BE0E-52D6-AA66-09CFA94D6943"><p>Network positioning </p> <p>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. </p> <p>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. </p> </li>

<li id="GUID-69E1FFDF-1D80-5555-B6CF-F617D4C6D832"><p>Other positioning technologies </p> <p>The

LBS subsystem can be extended to support other positioning technologies (such

as WLAN positioning). </p> <p>You can use the generic Positioning Plug-in

API to write ECom plug-ins to integrate with positioning hardware. </p> </li>

</ul> </section>

<section id="GUID-BA737C24-B56F-5796-9ECB-3BB1ABB8F179"><title>How applications

use the LBS subsystem </title> <p>There are three main ways that applications

and services use the LBS subsystem: </p> <ol id="GUID-7727B3F3-91F1-576B-8A23-79798F47A5C3">

<li id="GUID-24F4513E-8470-5A72-8CE2-3702AC46C600"><p>An installed application

wants to use the device's location. </p> <p>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. </p> <p>You

can use the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location

Acquisition API</xref> 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. </p> <p>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. </p> </li>

<li id="GUID-0F61D0C2-50FD-5931-8D46-652FE2995457"><p>An installed application

wants to send the location of the mobile device to a contact (phone number)

or URL over the network. </p> <p>You can use the <xref href="GUID-90757A79-A001-52BF-81D9-CFA02FDDE1BE.dita">Transmit

to Third Party API</xref> to send the user's location to a contact or service. </p> <p>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. </p> </li>

<li id="GUID-003735BF-5BF8-5CC6-A086-EC7069321D7E"><p>A network-based service

requests the location of the mobile device. </p> <p>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. </p> <p>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. </p> <p>In 3GPP terminology requests from the network

are known as MT-LR and Emergency MT-LR. MT-LR means Mobile Terminated Location

Request. </p> </li>

</ol> <p>Application developers who want to get started writing location enabled

applications may want to go directly to the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location

Acquisition API</xref> documentation which describes how to use the API. </p> </section>

<example id="GUID-38D6FCCB-C176-5759-B2E6-C6A5891A958B"><title>LBS components</title> <p>This

section gives an overview of the components of the LBS subsystem. </p> <p>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. </p> <p>Note:

figure 1 does not show all of the libraries that are part of the LBS subsystem. </p> <p>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. </p> <fig id="GUID-E0CF76DA-CEEB-5EC5-A700-1456F77E181B">

<title>              Figure 1. LBS subsystem components.            </title>

<image href="GUID-4F273D6C-073F-580B-8B1E-E23BECEFCAB1_d0e436155_href.png" placement="inline"/>

</fig> <p>The core components of the subsystem are as follows: </p> <ul>

<li id="GUID-BA03EDB6-7C03-555F-8DD7-2470471E33C5"><p>Location Server Framework </p> </li>

<li id="GUID-69726EC5-3811-55CB-A815-DEB9BF97D38F"><p>Positioning Framework </p> </li>

<li id="GUID-EA7480E1-B5D0-52C3-B99D-EB567D7D9706"><p>Network Request Handler </p> </li>

<li id="GUID-E7D1655D-8E5D-5D6B-A430-3D84C1AE5DF2"><p>Network Gateway </p> </li>

<li id="GUID-37B5314E-53F2-53CF-8EB7-0CD8C8F2FAF9"><p>Administration Services </p> </li>

<li id="GUID-4F3FB97A-3FC8-5673-A7F4-560AAB879E2A"><p>Logging Service </p> </li>

</ul> <p>The optional components of the LBS subsystem are as follows: </p> <ul>

<li id="GUID-31330F3C-02D6-580E-A326-1501289FB82B"><p>The components of the

Data Source Modules collection, which are Positioning Modules (PSYs): </p> <ul>

<li id="GUID-7076D645-6530-5AE4-A57B-3A511DC892B5"><p>The Default PSY </p> </li>

<li id="GUID-95B913D5-BA20-5D62-9174-5B9B69CD3A23"><p>The Bluetooth GPS PSY </p> </li>

<li id="GUID-2BADBF87-E072-559B-A997-4ECDC86F7D26"><p>The Simulation PSY </p> </li>

<li id="GUID-6ABD79C9-DC30-5C61-BFD3-EA87634B317D"><p>The GPS/A-GPS PSY </p> </li>

<li id="GUID-5C34E8C5-E997-59BC-ABE6-56CBADADFC00"><p>The Network PSY </p> </li>

</ul> <p>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. </p> </li>

<li id="GUID-120FABAF-9E26-5ED0-8CE6-0D3570D47D56"><p>The components of the

Network Protocol Modules collection: </p> <ul>

<li id="GUID-F6C70ECF-590D-5F27-8B38-897DAD56E33F"><p>The Privacy Protocol

Module </p> </li>

<li id="GUID-FE0B48BE-FC07-5A68-BF67-0B0096D6C77F"><p>The SUPL Protocol Module.

(The SUPL Proxy Protocol Module from Symbian^3 onwards)</p> </li>

</ul> </li>

</ul> <p id="GUID-F4B98D11-429D-5526-9D78-648E1D5C845B"><b>Location Server Framework</b> </p> <p>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 (<codeph>eposserver.exe</codeph>) that processes

the location requests. </p> <p>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 <xref href="GUID-893737B2-4863-5BB9-8AA1-6AB5045FADC9.dita">Positioning

Plug-in API</xref> (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. </p> <p>The

Location Server can obtain position data in one of three ways: </p> <ul>

<li id="GUID-7B03F3C1-B12C-553A-ABD7-93B8C7F3E621"><p>Directly from positioning

hardware (or a simulated source of positions) by using one of the pre-built

PSYs provided with the Symbian platform. </p> </li>

<li id="GUID-FCB71ABC-E4D7-52C8-8582-2C39F75A555C"><p>Directly from positioning

hardware by using a PSY developed by the device creator. </p> <p>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. </p> </li>

<li id="GUID-2E2C8C2E-150A-5F86-997D-399B88D7AA2E"><p>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: </p> <ul>

<li id="GUID-33EFCBC1-4A30-56C1-B9BA-5CFE7F116633"><p>The GPS/A-GPS PSY </p> <p>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 <xref href="GUID-8F2BA0D3-1549-5837-A105-3AB484CDB80B.dita">A-GPS

Integration Module</xref> and a <xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network

Protocol Module</xref>. </p> </li>

<li id="GUID-295CF0A0-62F0-5938-80EC-990469DDC769"><p>The Network PSY </p> <p>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 <xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network

Protocol Module</xref>. </p> </li>

</ul> </li>

</ul> <p>See <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location

Acquisition API</xref> documentation for a description of how to use the LBS

subsystem to get a location fix. </p> <p id="GUID-41A57E5B-29A2-5AAB-9C7B-223E04519139"><b>Positioning Framework</b> </p> <p>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. </p> <p><b>A-GPS

Location Manager</b> </p> <p>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. </p> <p>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. </p> <p>See <xref href="GUID-8F2BA0D3-1549-5837-A105-3AB484CDB80B.dita">A-GPS Integration Module</xref> for

information about the API that you must use to write an A-GPS Integration

Module. </p> <p><b>Network

Location Manager</b> </p> <p>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. </p> <p>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. </p> <p>See <xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network Protocol Module</xref> for

information about the API that you must use to write a Network Protocol Module. </p> <p><b>Location Monitor</b> </p> <p>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. </p> <p>See <xref href="GUID-16794D4F-23D7-5A96-B363-E25A3DD75C45.dita">Location Monitor</xref> for

a description of the Location Monitor component. </p> <p id="GUID-AEE6FC36-57DC-5D7B-8395-5204078F8689"><b>Network Request Handler</b> </p> <p>The

Network Request Handler has two main functions: </p> <ul>

<li id="GUID-2EDD87C4-43EE-531D-B5F3-BCBF236B8265"><p>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: </p> <ol id="GUID-9EC00AE8-EA81-5E81-9F94-45FB7118B1F1">

<li id="GUID-3D9A434A-C89D-5B5F-BC75-B5D0DBB2C366"><p>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). </p> </li>

<li id="GUID-E6BE2445-C63A-592D-9498-335A7C34652B"><p>A location request that

is processed if the privacy request is accepted. </p> </li>

</ol> <p>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. </p> <p>The Network Request Handler uses Privacy Notifiers

or a Privacy Controller to obtain a response to privacy requests: </p> <ul>

<li id="GUID-DA89B0C7-2B47-59F8-BDE0-D4132C9671BF"><p>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. </p> </li>

<li id="GUID-435DD9FF-33EB-5A48-9508-31B7A0C076A0"><p>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. </p> </li>

</ul> <p>An administration setting determines whether a Privacy Controller

or Privacy Notifiers are used. See <xref href="GUID-CDE5CC9D-F6DE-5A21-97C3-59A2F3398A15.dita">LBS

Privacy Requests</xref> for more information about how privacy requests are

handled. </p> </li>

<li id="GUID-56C88DD1-BF89-5C2D-A33A-F5DA986E921C"><p>Initiating and handling

requests to send the mobile device location to a remote party (MO-LR transmit

to third party). </p> <p>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. </p> <p>See <xref href="GUID-33BACB23-5BEB-5A1A-85B2-71E6AA7730C4.dita">Sending location to a third

party</xref> for more information. </p> </li>

</ul> <p id="GUID-F5590116-9517-51D6-9F72-A5DCC33BCF10"><b>Network Gateway</b> </p> <p>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: </p> <ul>

<li id="GUID-F19B4BE3-BB9E-5F80-BF81-B22AC25DC42F"><p>Receiving location requests

from the network (MT-LR, Emergency MT-LR and NI-LR) and forwarding them to

the Network Request Handler </p> </li>

<li id="GUID-D41763A3-2687-536F-834F-A32E2A49B84D"><p>Forwarding requests

for A-GPS assistance data to the network and receiving responses </p> </li>

<li id="GUID-C89715EE-E990-5348-B336-DC04F0F003D8"><p>Forwarding calculated

positions to the network </p> </li>

<li id="GUID-AB068989-1E62-5E5C-9313-CF6CCA18939A"><p>Forwarding GPS measurements

to the network and receiving the calculated positions (for A-GPS) </p> </li>

<li id="GUID-D8A1364B-E888-5A6A-8EEB-788F09144B28"><p>Forwarding a position

to a remote party over the network (MO-LR transmit to third party) </p> </li>

</ul> <p>To use the Network Gateway a device creator must develop and configure

at least one <xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network

Protocol Module</xref>  </p> <p id="GUID-28513912-D681-5BFF-9124-3A461DEAB7D8"><b>Administration Services</b> </p> <p>Administration

Services contains two main classes of components: </p> <ul>

<li id="GUID-93CA7D07-B23E-5C22-B8BC-5AC6A49305DF"><p>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. </p> </li>

<li id="GUID-BC37766C-7B8E-58AC-AF94-0C085FAC6A8D"><p>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 <xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita#GUID-7233BC33-6060-5D6B-A5D2-01135F059337/GUID-73A867D4-4C04-5B77-A117-14058F0C970E">LBS

APIs</xref> section of this document. </p> </li>

</ul> <p id="GUID-6689290E-90F2-5135-BEFE-5F612CB4606D"><b>Logging Service</b> </p> <p>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. </p> <p>See <xref href="GUID-66F29695-CED1-551C-976E-1A08C8059221.dita">LBS logging</xref> for more

information about using the Logging Service. </p> <p id="GUID-E5D66DF8-CD66-5DE5-A154-0780F4041EA6"><b>Data Source Modules</b> </p> <p>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. </p> <ul>

<li id="GUID-8456C81D-A265-5414-89A2-D224E69A0377"><p>The <xref href="GUID-ADE2ED06-A4F8-5216-A6EF-294D6B4766F7.dita">GPS/A-GPS

Positioning Module</xref> 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. </p> </li>

<li id="GUID-5B70ABC5-9C48-5AF1-856F-43CB0C3B1DF5"><p>The <xref href="GUID-5C01B66C-9F21-508F-A612-2ADAE1837A8A.dita">Network

Positioning Module</xref> connects the Location Server to the Network Location

Manager. It is the recommended way of getting a cell-based position from the

LBS subsystem. </p> </li>

<li id="GUID-40C72928-D475-52EB-A870-E3F672F940A4"><p>The <xref href="GUID-5454AFE9-ADC2-5980-85FC-3FF457B638D0.dita">Bluetooth

GPS Positioning Module</xref> connects the Location Server to an external

Bluetooth GPS device. It is the recommended way of getting a position from

a Bluetooth GPS device. </p> </li>

<li id="GUID-595C2E52-55BD-5A46-93F9-B07B0A50AED9"><p>The <xref href="GUID-1B3FDBF4-4213-5242-A05C-11ADE6C1501A.dita">Simulation

Positioning Module</xref> 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. </p> </li>

</ul> <p><b>Network

Protocol Modules</b> </p> <p>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: </p> <ul>

<li id="GUID-FD246037-10D6-5436-9B8B-96209FFD0652"><p>The <xref href="GUID-1F7F543A-8A9C-4460-BDB1-A6866E9DF0B9.dita">SUPL

Proxy Protocol Module</xref>  </p> <p>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 <xref href="GUID-816334A7-488B-5F91-8C2E-47076D875013.dita">SUPL

Protocol Module</xref>.</p> </li>

<li id="GUID-4C73516E-CAF4-54CB-ABF1-131D9B765362"><p>The <xref href="GUID-B27F6C1D-6815-5DF5-B3F8-449260030B3D.dita">Privacy

Protocol Module</xref>  </p> <p>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. </p> <p>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. </p> </li>

</ul> </example>

<section id="GUID-73A867D4-4C04-5B77-A117-14058F0C970E"><title>LBS APIs</title> <p>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. </p> <p><b>Location

Request APIs</b> </p> <table id="GUID-88C88B3E-E77F-5135-B807-EFF9176085B2">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Purpose</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location

Acquisition API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Positioning

Module APIs</b> </p> <table id="GUID-804C9F8C-E6EE-5B6C-8D66-5CC76F5765F6">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Purpose</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-893737B2-4863-5BB9-8AA1-6AB5045FADC9.dita">Positioning

Plug-in (PSY) API</xref>  </p> </entry>

<entry><p>Use the PSY API to create ECom plug-ins to connect the Location

Server to positioning hardware. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-DA2DC704-CE65-54FB-9049-4E1C73092EDF-GENID-1-10-1-16-1-1-10-1-5-1-5-1-8-1.dita">Positioning

Plug-in (PSY)Information API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-8F2BA0D3-1549-5837-A105-3AB484CDB80B.dita">A-GPS Location

Data Source API</xref>  </p> </entry>

<entry><p>Use the API to create an ECom plug-in to connect the LBS subsystem

(the A-GPS Manager) to internal A-GPS hardware. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Network

Protocol Module APIs</b> </p> <table id="GUID-B24BA6A5-5E29-5C72-8140-301105A903D1">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Purpose</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-8985B028-4BCD-5858-B22F-EECC52B7B9EB.dita">Network Protocol

Module API</xref>  </p> </entry>

<entry><p>Use the API to create an ECom plug-in to connect the LBS subsystem

to a network via the Network Gateway. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita">SUPL Push

API</xref>  </p> </entry>

<entry><p>Use this API to write ECom plug-ins to send SUPL Push messages to

the SUPL Protocol Module. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network Privacy

API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita"> Privacy

Request API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Privacy

Request APIs</b> </p> <table id="GUID-6D27527B-650E-5766-A342-B729B04A731D">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Purpose</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita">Privacy Controller

API</xref>  </p> </entry>

<entry><p>The API allows a device creator to build an application that automatically

processes privacy requests, with or without involving the mobile user. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23.dita">Privacy Notifiers

API</xref>  </p> </entry>

<entry><p>The API is used to develop notifiers to send simple privacy notification

and verification messages to the mobile user when privacy requests are received. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-8226320F-2F3A-575F-9950-B98C67472DAD.dita">Privacy Q&amp;N

API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Administration

Service APIs</b> </p> <table id="GUID-7C6D1FBD-01AF-5A88-AD85-5429D4AA6463">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Purpose</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration

API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita">Location

Settings API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita"> Integrated

GPS Hardware Status API</xref>  </p> </entry>

<entry><p>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. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita"> Positioning

Indicator API</xref>  </p> </entry>

<entry><p>A deprecated API used to get the status of GPS hardware. It is recommended

that the Integrated GPS Hardware Status API is used instead. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-0BA3A457-98BC-52FE-AF14-3B59806E01AA.dita">Quality Profile

API</xref>  </p> </entry>

<entry><p>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. </p> </entry>