LBS administration service overview

Purpose

This document describes the LBS administration service and the LBS Administration API which client applications use to get and set LBS administration settings.

Introduction

The LBS administration service allows client applications to get and set LBS administration settings. The service also allows applications to receive notification when administration settings are changed. Client applications use the service via the LBS Administration API.

Typical clients of the API are:

• 'Control panel' type applications that get and set LBS administration settings to configure LBS behaviour

• UI status bar components that display information about the status of LBS settings

The LBS Administration API is packaged in lbsadmin.dll. Client applications include lbsadmin.h and link against lbsadmin.lib. To set administration settings, an application must have the capability WriteDeviceData. No capabilities are required to read LBS administration settings.

Key concepts

LBS administration settings

The administration settings that configure LBS. They can be modified at runtime through the LBS Administration API by applications with the WriteDeviceData capability. LBS administration settings are stored in the central repository.

LBS administration repository initialisation file

Default values for LBS administration settings are defined in a repository initialisation file. The contents of the initialisation file can be set by Symbian licensees as part of the platform build and configuration process. The initialisation file is used to create a central repository at build time. The file cannot be modified at runtime.

Initially the central repository contains the default LBS administration settings values as defined in the repository initialisation file. The repository persists any changes to settings values made at runtime through the LBS Administration API. The API can also be used to revert the central repository to the default values in the initialisation file.

See LBS Administration Repository Initialisation File for more details.

LBS administration settings categories

LBS administration settings are classified into the following categories:

• Activation/deactivation of the different types of location request: Mobile Originated Location Requests (MO-LR), Mobile Terminated Location Requests (MT-LR) and Transfer Location to 3rd Party Requests (X3P)

• Quality profiles for MO-LR, MT-LR and X3P

• The mode of operation of GPS

• The network protocol module and how it is loaded by the LBS subsystem

• Use of Privacy Notifiers or a Privacy Controller for privacy requests and the default action to take on timeout of a privacy request

• The maximum number of privacy requests that can be handled simultaneously by the LBS subsystem

• Specification of the GPS set clock module and whether manual or automatic updates to the system clock are allowed

• A setting to turn logging on or off in the LBS subsystem

• 'Special feature' settings (see below)

Special feature settings

A set of read-only 'special feature' administration settings allows configuration of LBS runtime behaviour by Symbian licensees. These settings must be configured in the LBS administration repository initialisation file and cannot be set at runtime via the LBS Administration API.

There are several special feature settings which define:

• The time to buffer position updates and error codes in LBS when there is no current RPositioner::NotifyPositionUpdate()

• The values of TPositionInfo::PositionMode() for final network positions

• Whether inaccurate positions should be returned to client applications

• Whether reference positions should be returned to client applications

• How "futile" updates from a licensee's A-GPS Integration Module are handled

See Special feature settings for more information.

API summary

Client applications use the LBS administration service via the LBS Administration API.

The API is defined by the following header files:

Applications include lbsadmin.h which includes the other header files.

The API defines two main classes, shown in figure 1:

• CLbsAdmin

  Applications use CLbsAdmin to get and set administration settings and to register for notification of administration settings changes.

• MLbsAdminObserver

  Applications use an object derived from MLbsAdminObserver to receive notification of changes to administration settings.

CLbsAdmin

Applications use CLbsAdmin for the following:

• Accessing LBS administration settings

• Resetting administration settings to the default

• Receiving notification of administration settings changes

Each of these uses is described in the following sections.

Accessing LBS administration settings

CLbsAdmin::Get() and CLbsAdmin::Set() get and set LBS administration settings.

The full signatures of CLbsAdmin::Get() and CLbsAdmin::Set() are as follows:

• template <typename T> inline TInt Set(const TLbsAdminSetting& aSetting, const T& aValue);

• template <typename T> inline TInt Get(const TLbsAdminSetting& aSetting, T& aValue) const;

The use of template methods allows the interface of CLbsAdmin to be simplified: all administration settings are queried and modified by use of the same Get() and Set() methods.

CLbsAdmin::Get() and CLbsAdmin::Set() take two parameters:

• A constant of type TLbsAdminSetting that specifies the administration setting that is set or returned. TLbsAdminSetting constants are defined in lbsadminsettings.h.

• A reference to hold the value of the administration setting to be set or returned. Many administration setting values are defined by a set of enumerated types defined in lbsadmindatatypes.h.

The following list describes the purpose of each of the LBS administration settings defined by the TLbsAdminSetting constants:

• KLbsSettingHomeSelfLocate

  Purpose: Configures self location requests (MO-LR) in the home network. This setting turns self location requests on or off.

  Values: Defined by CLbsAdmin::TSelfLocateService

• KLbsSettingRoamingSelfLocate

  Purpose: Configures self location requests (MO-LR) when roaming. This setting turns self location requests on or off.

  Values: Defined by CLbsAdmin::TSelfLocateService

• KLbsSettingHomeExternalLocate

  Purpose: Configures external location requests (MT-LR) in the home network. This setting turns external location requests on or off. It also defines if user permission for external requests should always be obtained when external locate is on, and if the user should always be notified of rejected external location requests when external locate is off.

  Note that the value of this setting does not affect emergency services location requests (Emergency MT-LR) which are always accepted.

  Values: Defined by CLbsAdmin::TExternalLocateService. The value EExternalLocateOnButAlwaysVerify must not be used with the Network Privacy API as a privacy verification response cannot be returned for a privacy notification that was sent using this API.

• KLbsSettingRoamingExternalLocate

  Purpose: Configures external location requests (MT-LR) when roaming. See KLbsSettingHomeExternalLocate above.

  Values: Defined by CLbsAdmin::TExternalLocateService. See KLbsSettingHomeExternalLocate above.

• KLbsSettingHomeTransmitLocate

  Purpose: Configures transmit to third party location requests (X3P) in the home network. This setting turns transmit to third party requests on or off.

  Values: Defined by CLbsAdmin::TTransmitLocateService

• KLbsSettingRoamingTransmitLocate

  Purpose: Configures transmit to third party location requests (X3P) when roaming. This setting turns transmit to third party requests on or off.

  Values: Defined by CLbsAdmin::TTransmitLocateService

• KLbsSettingQualityProfileSelfLocate

  Purpose: Defines the quality profile used for MO-LR. This setting specifies a quality profile ProfileID for self location requests as defined in the quality profile file lbsprofile.ini.

  Values: Defined by CLbsAdmin::TLbsQualityProfileId

• KLbsSettingQualityProfileExternalLocate

  Purpose: Defines the quality profile used for MT-LR. This setting specifies a quality profile ProfileID for external location requests as defined in the quality profile file lbsprofile.ini.

  Values: Defined by CLbsAdmin::TLbsQualityProfileId. A value of KLbsNoProfileInUseQualityProfileId means that a profile is not used when KSettingLbsBehaviourMode is set to CLbsAdmin::ELbsBehaviourModeOriginal. LBS uses quality criteria received as part of the external locate request.

• KLbsSettingHomeTransmitLocate

  Purpose: Defines the quality profile used for X3P. This setting specifies a quality profile ProfileID for transmit to third party requests as defined in the quality profile file lbsprofile.ini.

  Values: Defined by CLbsAdmin::TLbsQualityProfileId

• KLbsSettingHomeGpsMode

  Purpose: Configures the GPS mode in the home network. This setting specifies how LBS uses GPS to obtain a position fix. Note that this is the default setting. The network can override this setting as part of a location request.

  Values: Defined by CLbsAdmin::TGpsMode

• KLbsSettingRoamingGpsMode

  Purpose: Configures the GPS mode when roaming. See KLbsSettingHomeGpsMode above.

  Values: Defined by CLbsAdmin::TGpsMode

• KLbsSettingHomeProtocolModule

  Purpose: Specifies the UID of the Network Protocol Module to use in the home network.

  Values: Defined by TUid

• KLbsSettingRoamingProtocolModule

  Purpose: Specifies the UID of the Network Protocol Module to use when roaming.

  Values: Defined by TUid

• KLbsProtocolModuleLoading

  Purpose: Defines the Network Protocol Module loading strategy - whether a module or modules are loaded on subsystem startup or based on network registration status.

  Values: A value defined by TLbsAdminProtocolModuleLoadingInfo::_TProtocolModuleLoading which have the following meanings:

  • EProtocolModuleLoadingAll

    A value of TLbsAdminProtocolModuleLoadingInfo::EProtocolModuleLoadingAll causes the two Network Protocol Modules specified by the settings KLbsSettingHomeProtocolModule and KLbsSettingRoamingProtocolModule to be loaded when the LBS subsystem starts. The modules are not unloaded until the LBS subsystem is shutdown.

    At any time, only one module can be active - loading a module does not make it active. Only an active module can be used to process location requests. LBS uses changes to the network registration status of the mobile device to decide which module is active. If the mobile device moves from the home network to roaming (or vice versa) the appropriate module is made active without the need to restart the device.

  • EProtocolModuleLoadingByStatus

    A value of TLbsAdminProtocolModuleLoadingInfo::EProtocolModuleLoadingByStatus means that one Network Protocol Module is loaded on LBS startup based on the network registration status.

    When LBS receives the first network registration status update (which should be soon after startup) it loads either the home or the roaming Network Protocol Module depending on the registration status. Only one module is loaded. Changes to the registration status (for example from the home network to roaming) do not cause a second module to be loaded. This means that if a licensee uses different Network Protocol Modules in the home network and roaming, it is necessary to restart the device when moving between networks in order to load the appropriate Network Protocol Module.

    Note that this is the default LBS behaviour based on the value in the administration repository initialisation file.

  If LBS cannot obtain the device's network registration status, a Network Protocol Module cannot be made active and a location request that uses it will fail.

  The setting has no effect if the Privacy Protocol Module is specified for use: it is loaded and active when the LBS subsystem starts without waiting for a network registration status.

• KLbsSettingPrivacyHandler

  Purpose: Specifies use of a Privacy Controller or Privacy Notifiers. Either a Privacy Controller or Privacy Notifiers are used to inform the user when an external privacy or location request (MT-LR or NI-LR) is received.

  Values: Defined by CLbsAdmin::TPrivacyHandler

• KLbsSettingPrivacyAppTimeout

  Purpose: Specifies the time in microseconds that LBS waits for a response from a Privacy Controller or Privacy Notifier. A value of zero means the LBS nevers times out the request. The setting must be set in the repository initialisation file and cannot be set at runtime.

  Values: A time in microseconds.

• KLbsSettingPrivacyTimeoutAction

  Purpose: Specifies the action to take on timeout of a MT-LR privacy request. This setting specifies if LBS should send a rejection message or take the action specified as part of the MT-LR privacy request message.

  Values: Defined by CLbsAdmin::TPrivacyTimeoutAction

• KLbsSettingMaximumExternalLocateRequests

  Purpose: Specifies the maximum number of simultaneous privacy requests supported by the LBS subsystem. The setting only affects LBS subsystem behaviour when privacy requests are received via either the Privacy Request API or the Network Privacy API. This setting is read only on LBS system startup. Setting it via the LBS Admin API has no effect while is LBS running. The setting will take effect during the next LBS system startup.

  Values: The value 0 is reserved for future use. The value 1 is the default, this allows only one active external locate request at a time. Values greater than 1 allow multiple requests to be handled simultaneously.

• KLbsSettingPrivacyShutdownDelay

  Purpose: The time to wait after the last privacy client disconnects before shutting down LBS. Only used with the Network Privacy API and the Privacy Request API. This setting is read only on LBS system startup. Setting it via the LBS Admin API has no effect while LBS running. Setting will take effect during next LBS system startup.

  Values:An integer value in microseconds.

• KLbsSettingPrivacyMaxNetworkSessions

  Purpose: The maximum number of concurrent network privacy sessions allowed with the Network Privacy API. This setting is read only on LBS system startup. Setting it via the LBS Admin API has no effect while LBS running. Setting will take effect during next LBS system startup.

  Values: An integer value. The value 0 disallows any network privacy sessions.

• KLbsSettingPrivacyConnectionTimeout

  Purpose: The connection timeout for sessions using the Network Privacy API. This setting is read only on LBS system startup. Setting it via the LBS Admin API has no effect while LBS running. Setting will take effect during next LBS system startup.

  Values: An integer value in microseconds.

• KLbsSettingClockAdjust

  Purpose: Configuration of automatic system clock synchronisation with GPS. This setting specifies if automatic clock synchronisation is on or off.

  Values Defined by CLbsAdmin::TClockAdjust

• KLbsSettingSetClockModule

  Purpose: Configuration of the set clock module. This setting specifies the implementation UID of a licensee clock plug-in DLL. This value is 0 to use the default Symbian set clock implementation.

  Values: A TUid value

• KLbsSettingClockAdjustInterval

  Purpose: Specifies the system clock adjustment interval in milliseconds. This setting specifies how often the system clock should be synchronised with the GPS clock. The setting is used only if the KLbsSettingAllowClockAdjust is set to allow automatic system clock adjustment.

  Values: A CLbsAdmin::TLbsTimeIntervalMiliSeconds value

• KLbsSettingClockAdjustThreshold

  Purpose: Configures the system clock adjustment interval in milliseconds. This setting specifies how great the difference in time between the system clock and the GPS clock must be before the system clock is adjusted.

  Values: A CLbsAdmin::TLbsTimeIntervalMiliSeconds value

• KLbsSettingLogger

  Purpose: Turns logging on or off in the LBS subsystem.

  Values: A CLbsAdmin::TLogger value

• KLbsSettingBehaviourMode

  Purpose: Specifies the behaviour mode for the LBS subsystem. The setting must be set in the repository initialisation file and cannot be set at runtime via the LBS Administration API as it is used by the LBS subsystem on startup.

  Values: Defined by CLbsAdmin::TLbsBehaviourMode. See repository initialisation file for more information.

Special feature settings

• KLbsSpecialFeatureMaximumRequestDelay

  Purpose: Specifies the length of time that location updates and error codes received from a positioning module are temporarily buffered in LBS.

  Values: A time in milliseconds

• KLbsSpecialFeatureAllowTBFinalNetPos

  Purpose: Specifies how LBS handles final network position updates.

  Values: A CLbsAdmin::TSpecialFeature value.

• KLbsSpecialFeatureIgnoreAccuracy

  Purpose: Configures LBS to either return only accurate position updates or all position updates including inaccurate ones.

  Values: A CLbsAdmin::TSpecialFeature value.

• KLbsSpecialFeatureWithholdDeliveryOfReferencePositions

  Purpose: Specifies if LBS should deliver reference positions to a client application when RPositioner::Open() is called with a GPS module ID.

  Values: A CLbsAdmin::TSpecialFeature value.

• KLbsSpecialFeatureIntermediateFutileUpdate

  Purpose: Specifies if LBS should return a "futile" update from a licensee A-GPS Integration Module to the network when there is no outstanding location request.

  Values: A CLbsAdmin::TSpecialFeature value.

The special feature settings cannot be set via the LBS Administration API and so must be set in the LBS administration repository file. Special feature settings has more information on the behaviour of LBS that is modified by the special feature settings.

Unused settings

Note that there are some additional settings defined in lbsadmin.h: KLbsSettingHomeEmergencyLocate, KLbsSettingRoamingEmergencyLocate, KLbsSettingRoamingProtocolModule and KLbsSettingLbsSystemStartMode. These are not used and setting them has no effect.

Accessing LBS administration settings describes how to get and set LBS administration settings.

Resetting administration settings to the default

Calling CLbsAdmin::ResetToDefault() causes LBS administration settings to be reset to the default values defined in the LBS administration settings initialisation file. These default settings are persisted in the central repository.

Resetting the administration settings shows how to reset the administration settings to their default values.

Receiving notification of administration settings changes

To register an observer object to receive notifications of LBS administration settings changes, CLbsAdmin::NewL() is called with two parameters:

• An observer object derived from MLbsAdminObserver

• A TLbsAdminSettingGroup object

  A TLbsAdminSettingGroup object defines a bitmask of TLbsAdminSetting constants. An observer is notified when there is a settings change in one of the settings defined in the bitmask.

CLbsAdmin::SetNotificationMaskL() sets a new bitmask and CLbsAdmin::ClearNotificationMask() clears the bitmask.

Receiving notifications of LBS administration settings changes shows how to register an observer object and receive settings change notifications.

MLbsAdminObserver

Applications use an object derived from MLbsAdminObserver to receive notifications of LBS administration settings changes.

LBS calls MLbsAdminObserver::OnSettingUpdateEvent() to notify an observer that a setting has changed.

Receiving notifications of LBS administration settings changes

Typical uses

A 'control panel' type of application uses the LBS Administration API to manage the configuration of the LBS subsystem.

Accessing LBS administration settings shows how to use the API to configure LBS.

A UI status bar component uses the LBS Administration API to receive notification of LBS subsystem configuration changes.

Receiving notification of LBS settings changes shows how to use the API to get notification of LBS administration changes.

See also

How to use the LBS Administration API

The LBS administration repository initialisation file