LBS ROM Macros

Location Server macros

The LBS subsystem can be configured to contain one of two Location Servers. The choice of Location Server has a significant impact on the components and features that can be supported by the LBS subsystem:

• The Location Server Framework

  The Location Server Framework consists of the Location Server eposserver.exe and supporting libraries and APIs. It was previously available only as part of the S60 platform but is now part of the Symbian platform.

  The macro SYMBIAN_INCLUDE_LOCATION_API_VARIANT2 includes the Location Server Framework in ROM. If this macro is not used at ROM build time the Location Server Framework is not included in ROM. If the macro is used, other related macros may also be defined to include Positioning Plug-ins (PSYs) that can be used by the Location Server Framework:

  • SYMBIAN_INCLUDE_BLUETOOTH_GPS_PM includes the Bluetooth GPS PSY in ROM.

    This PSY connects the Location Server to external Bluetooth GPS hardware.

  • SYMBIAN_INCLUDE_SIMULATION_PM includes the Simulation PSY in ROM.

    This PSY enables application developers to easily test their location-based applications on an emulator or on hardware.

  • SYMBIAN_INCLUDE_DEFAULT_PM includes the Default Positioning Module (PSY) in ROM.

    This PSY can delegate location requests to other installed PSYs. It is used to select the PSYs to which location requests are sent when a client application of the Location Acquisition API does not specify a PSY UID.

  There are also macros that you can use to include the PSYs to connect the Location Server to the Positioning Framework. It is necessary to use these macros in order to use the Positioning Framework to obtain GPS/A-GPS or network-based positions for the Location Server.

  • SYMBIAN_INCLUDE_LOCATION_AGPS_PM includes the GPS/A-GPS PSY and must be specified if you want the Location Server to use an A-GPS Integration Module to get position fixes using assisted GPS.

  • SYMBIAN_INCLUDE_LOCATION_GPS_PM includes the GPS/A-GPS PSY and must be specified if you want the Location Server to use an A-GPS Integration Module to get position fixes using autonomous GPS.

  • SYMBIAN_INCLUDE_LOCATION_AGPS_PM and SYMBIAN_INCLUDE_LOCATION_GPS_PM must both be specified if you want the Location Server to use an A-GPS Integration Module to get position fixes using either assisted GPS or autonomous GPS.

  • SYMBIAN_INCLUDE_LOCATION_NETWORK_PM includes the Network PSY and must be specified if you want the Location Server to use a Network Protocol Module to connect to the network to use cell based positioning.

Standalone Privacy Mode macros

Macros are also defined to allow LBS to be built with a Privacy Protocol Module that receives LBS privacy requests from the device native OS:

• SYMBIAN_INCLUDE_LOCATION_PRIVACY_REQUEST_APIS includes the binaries associated with the Privacy Protocol Module.

  The Privacy Protocol Module and its APIs allow privacy requests to be sent from the device's native OS into the LBS subsystem.

  Note: A location request from the network (MT-LR) consists of two parts: a privacy request and a following location request. The Privacy Protocol Module can handle only the privacy request and return a privacy response. It cannot handle the location request part. You must implement your own solution for handling the location request in the device native OS.

• SYMBIAN_INCLUDE_LOCATION_ADVANCED_DIALOG

  The macro is used to include the Privacy Query and Notification API binaries in ROM. Note that the Privacy Controller API and Privacy Notifiers API are always included even if this macro is not used.

Specifying the .iby files

The LBS .iby files used by buildrom are exported to <EPOC_ROOT>/epoc32/rom/include. The following defines the list of all .iby files that are necessary to add LBS to a ROM. Note that many of these 'top-level' .iby files include other LBS .iby files. The iby files contain checks for the ROM build macros to control whether the different components of LBS are included in ROM.

#if !defined(SYMBIAN_EXCLUDE_LOCATION)

#include "lbsadmin.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2 

#include "lbslocserver.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2 
                               and SYMBIAN_EXCLUDE_LOCATION_MANAGEMENT

#include "lbsagpslocmanager.iby" // Includes check for SYMBIAN_EXCLUDE_LOCATION_MANAGEMENT

#include "LbsNetworkLocationManager.iby" // Includes check for SYMBIAN_EXCLUDE_LOCATION_MANAGEMENT

#include "lbsnetworkrequesthandler.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_ADVANCED_DIALOG
                                           in included .iby files

#include "lbsnetgateway.iby" 

#include "lbs_privacyprotocolmodule.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_PRIVACY_REQUEST_APIS
                                            in included .iby files

#if defined(SYMBIAN_INCLUDE_LOCATION_API_VARIANT2)
 
#include "lbsbtgpspsy.iby" // Includes check for SYMBIAN_INCLUDE_BLUETOOTH_GPS_PM

#include "lbssimulationpsy.iby" // Includes check for SYMBIAN_INCLUDE_SIMULATION_PM

#include "lbsdefaultpsy.iby" // Includes check for SYMBIAN_INCLUDE_DEFAULT_PM

#include "lbsgpsagpspsy.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2

#include "lbsnetpsy.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2

#include "lbspsytester.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2

#include "lbspospluginfw.iby" // Includes check for SYMBIAN_INCLUDE_LOCATION_API_VARIANT2

#endif // SYMBIAN_INCLUDE_LOCATION_API_VARIANT2

#endif // SYMBIAN_EXCLUDE_LOCATION

Note: if the macro SYMBIAN_EXCLUDE_LOCATION is defined at ROM build time all the components of the LBS subsystem are excluded from ROM.

Using the macros to build LBS ROM images

This section describes how different LBS subsystem ROM images can be built using the ROM build macros to include or exclude optional LBS components.

• Full LBS on the Symbian platform

  This configuration contains all of the core components of LBS and excludes the Privacy Protocol Module.

  You must develop a Network Protocol Module if the LBS subsystem must be connected to the network. You can include those PSYs that you wish to support.

  The following shows the commands to build the ROM image, including all PSYs that are provided with the Symbian platform:

  
  buildrom lbs.oby 
  -DSYMBIAN_INCLUDE_LOCATION_API_VARIANT2
  -DSYMBIAN_INCLUDE_DEFAULT_PM
  -DSYMBIAN_INCLUDE_BLUETOOTH_GPS_PM
  -DSYMBIAN_INCLUDE_SIMULATION_PM
  -DSYMBIAN_INCLUDE_LOCATION_AGPS_PM
  -DSYMBIAN_INCLUDE_LOCATION_GPS_PM
  -DSYMBIAN_INCLUDE_LOCATION_NETWORK_PM
  

• LBS in Standalone Privacy Mode

  This configuration contains all of the core components of LBS and includes the Privacy Protocol Module.

  In this configuration, the LBS components of the Symbian platform can handle only the privacy request part of an MT-LR. The location request part of the MT-LR must be handled in the device native OS.

  Note: this configuration must not be used to support emergency services requests, as behaviour in low memory conditions is not guaranteed.

  The following shows the commands to build the ROM image:

  
  buildrom lbs.oby 
  -DSYMBIAN_INCLUDE_LOCATION_API_VARIANT2
  -DSYMBIAN_EXCLUDE_LOCATION_MANAGEMENT
  -DSYMBIAN_INCLUDE_LOCATION_PRIVACY_REQUEST_APIS
  -DSYMBIAN_INCLUDE_LOCATION_ADVANCED_DIALOG
  -DSYMBIAN_INCLUDE_DEFAULT_PM
  -DSYMBIAN_INCLUDE_BLUETOOTH_GPS_PM
  -DSYMBIAN_INCLUDE_SIMULATION_PM
  

  The Privacy Protocol Module and its APIs (the Network Privacy API and the Privacy Request API) are included in the ROM image. Positioning Framework components are excluded by using SYMBIAN_EXCLUDE_LOCATION_MANAGEMENT and the Privacy Query and Notification API is included. The Privacy Query and Notification API is only required if you want to create privacy notifiers using the API.