The LBS Administration Repository Initialisation File

This topic describes the LBS administration repository initialisation file.

Required background

LBS administration service overview describes the LBS administration service and the LBS Administration API.

Introduction

The repository initialisation file is used to create default LBS administration settings in the central repository.

The contents of the initialisation file can be changed as part of the Symbian platform build and configuration process. Changing the contents of the file changes the LBS administration settings that are applied when LBS starts for the first time.

The settings defined in the initialisation file are applied to the LBS subsystem by calling CLbsAdmin::ResetToDefault().

The repository initialisation file

The file <LBS_ROOT>\LbsAdmin\data\1028224B.txt (shown below) is the source text initialisation file of the LBS administration service. <LBS_ROOT> is the root directory of the Symbian LBS subsystem distribution.



# 1.0 File Version For LBS Administration API

# This file is compiled into the binary '.cre' version
# by an extension makefile (createbinaryrep.mk), which
# is called as part of the standard abld build process.
#
# The ".cre" version is the one used to install the 
# repository when the ROM is built. 

cenrep
version 1

[Platsec]
cap_rd=AlwaysPass
cap_wr=WriteDeviceData

[Main]
#KSettingHomeSelfLocate. ESelfLocateOn
0x00000001  int  1
#KSettingRoamingSelfLocate. ESelfLocateOff
0x00000002  int  2
#KSettingQualityProfileSelfLocate. Profile 0
0x00000003  int  0
#KSettingHomeExternalLocate. EExternalLocateOn
0x00000004  int  1
#KSettingRoamingExternalLocate. EExternalLocateOn
0x00000005  int     1
#KSettingQualityProfileExternalLocate. Profile 0
0x00000006  int  0
#KSettingHomeEmergencyLocate. EExternalLocateOn
0x00000007  int  1
#KSettingRoamingEmergencyLocate. EExternalLocateOn
0x00000008  int  1
#KSettingHomeTransmitLocate. ETransmitLocateOn
0x00000009  int  1
#KSettingRoamingTransmitLocate. ETransmitLocateOn
0x0000000A  int  1
#KSettingQualityProfileTransmitLocate. Profile 0
0x0000000B  int  0
#KSettingHomeGpsMode. EGpsPreferTerminalBased
0x0000000C  int     1
#KSettingRoamingGpsMode. EGpsAutonomous
0x0000000D  int     3
#KSettingHomeProtocolModule. Protocol Id 0
#The following is a test plug-in and must be changed to device creator implementation or SUPL reference module UID
0x0000000E  int  0x10281D70
#KSettingRoamingProtocolModule. Protocol Id 0
0x0000000F  int  0
#KSettingLbsSystemStartMode. ELbsSystemPersistent
0x00000010  int  2
#KSettingPrivacyTimeoutAction. EPrivacyTimeoutNetworkDefined
0x00000011  int  1
#KSettingPrivacyHandler. EPrivacyHandleByNotifier
0x00000012  int  1
#KSettingLbsBehaviourMode. ELbsBehaviourCustom1
0x00000013  int  2
#KLbsSettingLogger. ELoggerOn
0x00000014  int  1
#KLbsSpecialFeatureMaximumRequestDelay. Timeout of 0 denotes feature off.
0x00000015  int  0
#KLbsSpecialFeatureAllowTBFinalNetPos. Feature off.
0x00000016  int  2
#KLbsSpecialFeatureWithholdDeliveryOfReferencePositions. Feature off.
0x00000017  int  2
#KLbsProtocolModuleLoading
0x00000018  int  1
#KLbsSettingMaximumExternalLocateRequests. Value: 1
0x00000019  int  1
#KLbsSettingPrivacyShutdownDelay. Value: 2000000 (2 seconds)
0x0000001A  int  2000000
#KLbsSettingPrivacyMaxNetworkSessions. Value: 4
0x0000001B  int  4
#KLbsSettingPrivacyConnectionTimeout. Value: 30000000 (30 seconds)
0x0000001C  int  30000000
#KLbsSpecialFeatureIgnoreAccuracy. Feature off.
0x0000001E  int  2
#KLbsSettingPrivacyAppTimeout in milliseconds value: 20s
0x0000001F  int  20000
#KLbsSpecialFeatureIntermediateFutileUpdate. Feature off.
0x00000020  int  2
#KLbsSettingHomeNetworkInducedLocate. EExternalLocateOff
0x00000021  int  3
#KLbsSettingRoamingNetworkInducedLocate. EExternalLocateOff
0x00000022  int  3
#KLbsSettingSetClockModule. Id 0. Use the default, internal implementation.
0x0000003C  int  0x00000000
#LbsSettingClockAdjustInterval in miliseconds. Value: 7days
0x0000003D  int  604800000
#KLbsSettingClockAdjustThreshold in miliseconds. Value: 1s
0x0000003E  int  1000
#KSettingClockAdjust. EClockAdjustOn
0x00000040  int  1

The format of entries is <ID> <type> <value> where <ID> must be one of the hexadecimal values shown, <type> must be int and <value> must be one of the values defined by the enumerated types shown in the following list.

Note that it is necessary to use a numerical value for <value> rather than the enumerated type value.

  • 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. See table below.

    TSelfLocateService Numerical value

    ESelfLocateOn

    1

    ESelfLocateOff

    2

  • KLbsSettingRoamingSelfLocate

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

    Values: Defined by CLbsAdmin::TSelfLocateService. See table above.

  • 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.

    Values: Defined by CLbsAdmin::TExternalLocateService. See table below.

    TExternalLocateService Numerical value

    EExternalLocateOn

    1

    EExternalLocateOnButAlwaysVerify

    2

    EExternalLocateOff

    3

    EExternalLocateOffButNotify

    4

    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 table 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. See table below.

    TTransmitLocateService Numerical value

    ETransmitLocateOn

    1

    ETransmitLocateOff

    2

  • 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. See table above.

  • 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.

    Changes to this setting do not change the quality criteria used for RPositioner subsessions that are already open. Only subsessions opened after this value is changed use the different quality profile.

    Values: The value of a ProfileID in file lbsprofile.ini

  • 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: The value of a ProfileID in file lbsprofile.ini but 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.

    The quality profile values in lbsprofile.ini are only used if the quality criteria supplied by the network is incomplete or invalid.

    Values: The value of a ProfileID in file lbsprofile.ini

  • KLbsSettingHomeGpsMode

    Purpose: Configures the GPS mode in the home network. This setting specifies how LBS uses GPS to obtain a position fix.

    Values: Defined by CLbsAdmin::TGpsMode. See table below.

    TGpsMode Numerical value

    EGpsPreferTerminalBased

    1

    EGpsAlwaysTerminalBased

    2

    EGpsAutonomous

    3

    EGpsPreferTerminalAssisted

    4

    EGpsAlwaysTerminalAssisted

    5

  • KLbsSettingRoamingGpsMode

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

    Values: Defined by CLbsAdmin::TGpsMode. See table above.

  • KLbsSettingHomeProtocolModule

    Purpose: Defines the UID of the network protocol module to be used in the home network.

    Values: The UID of the ECom network protocol module plug-in as specified by the implementation_uid value in the ECom resource file.

  • KLbsSettingRoamingProtocolModule

    Purpose: Defines the UID of the network protocol module to be used when roaming.

    Values: The UID of the ECom network protocol module plug-in as specified by the implementation_uid value in the ECom resource file.

  • KLbsProtocolModuleLoading

    Purpose: Defines the network protocol module loading strategy - whether both protocol modules are loaded on subsystem startup or based on network registration status.

    Values: Defined by TLbsAdminProtocolModuleLoadingInfo::_TProtocolModuleLoading. See table below for the numerical values and LBS administration service for a full explanation of the meanings.

    _TProtocolModuleLoading Numerical value

    EProtocolModuleLoadingByStatus

    1

    EProtocolModuleLoadingAll

    2

  • KLbsSettingPrivacyHandler

    Purpose: Specifies use of a Privacy Controller or Privacy Notifiers. Either a Privacy Controller, Privacy Notifiers or the Privacy Q&N Notifiers are used to inform the user when a privacy/location request is received from the network.

    Values: Defined by CLbsAdmin::TPrivacyHandler. See table below.

    TPrivacyHandler Numerical value

    EPrivacyHandleByNotifier

    1

    EPrivacyHandleByController

    2

    EPrivacyHandleByAdvancedNotifier

    3

  • 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. See table below.

    TPrivacyTimeoutAction Numerical value

    EPrivacyTimeoutNetworkDefined

    1

    EPrivacyTimeoutReject

    2

    EPrivacyTimeoutIgnore

    3

  • 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. See table below.

    TClockAdjust Numerical value

    EClockAdjustOn

    1

    EClockAdjustOff

    2

  • KLbsSettingSetClockModule

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

    Values: 0 to use the default LBS set clock module, or the UID of a plug-in as specified by the implementation_uid value in the ECom resource file.

  • 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 time in milliseconds

  • 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 time in milliseconds

  • KLbsSettingLogger

    Purpose: Specifies if logging is on or off. LBS subsystem components use this setting to decide whether to write log entries.

    Values: Defined by CLbsAdmin::TLogger. See table below.

    TLogger Numerical value

    ELoggerOn

    1

    ELoggerOff

    2

  • 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 LBS running. Setting will take effect during 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.

  • 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 table below.

    TLbsBehaviourMode Numerical value

    ELbsBehaviourModeOriginal

    1

    ELbsBehaviourCustom1

    2

    The value ELbsBehaviourModeCustom1 is used as the default LBS behaviour if the setting is not included in the file. Note that ELbsBehaviourCustom1 is the default LBS behaviour and the only behaviour possible prior to Symbian OS v9.4.

    The behaviour differences are as described in the following table.

    LBS Behaviour ELbsBehaviourCustom1 (default) ELbsBehaviourModeOriginal

    Behaviour when tracking with Location Acquisition API

    When tracking, positions calculated in the network are not returned to the client.

    When tracking, positions calculated in the network can be returned to a client.

    MO-LR transmit to third party timeout (X3P) behaviour

    When an X3P request is made in LBS a timer is started. As part of the X3P request a location request is received from the network. The network can send more than one request. If LBS is in simultaneous TB + TA mode, the X3P request timer is restarted when the first location request is received from the network.

    The X3P request timer is not restarted when the first location request is received from the network.

    Behaviour when an MT-LR privacy request is received.

    LBS always rejects a privacy request if the quality profile ID specified by KLbsSettingQualityProfileExternalLocate is invalid (it cannot be found in lbsprofile.ini file).

    If the quality profile ID specified by KLbsSettingQualityProfileExternalLocate is KLbsNoProfileInUseQualityProfileId LBS does not try to find it in lbsprofile.ini. LBS expects all quality criteria to be supplied with the location request.

Note that the settings KLbsSettingHomeEmergencyLocate, KLbsSettingRoamingEmergencyLocate, KLbsSettingRoamingProtocolModule and KLbsSettingLbsSystemStartMode are not used and changing their value has no effect.

Special feature settings

The repository initialisation file also includes 'special feature' settings that have names prefixed KLbsSpecialFeature. These settings affect low-level, runtime behaviour of LBS for specific circumstances. The settings are intended to allow licensees and partners to configure the detailed runtime behaviour of LBS at subsystem build time. The settings are therefore read-only and can only be changed in the repository initialisation file and not via the LBS Admin API.

The special feature settings are:

  • KLbsSpecialFeatureMaximumRequestDelay

    Purpose: This setting specifies the length of time that the following location updates and error codes are temporarily buffered in LBS:

    • A single reference location received from the network

    • A single final network location received from the network

    • A single error code received from an A-GPS Module

    Buffering of location updates and error codes ensures that they are not lost when the LBS subsystem has no outstanding location request. This behaviour can occur in the following circumstances:

    1. A client application calls RPositioner::NotifyPositionUpdate().

    2. A location update or error code is generated in LBS. The client application's CActive::RunL() method is called but the next call to RPositioner::NotifyPositionUpdate() in that method is not yet reached.

    3. A reference location, final network location or AGPS error code is generated.

      • If KLbsSpecialFeatureMaximumRequestDelay is not set in the repository initialisation file (or is set to 0) then the client cannot be notified of the update because it has not yet called RPositioner::NotifyPositionUpdate() in its RunL() method.

      • If KLbsSpecialFeatureMaximumRequestDelay is set then LBS buffers the location or error code for the specified length of time. If the client calls NotifyPositionUpdate() within that time then the buffered location or error code can be returned.

    Values: The time is defined in milliseconds and is of type TLbsTimeIntervalMiliSeconds. A value of 0 disables this feature and is the default if this setting is not set in the repository initialisation file. The maximum value that should be set is KLbsMaximumRequestDelayMax. Under normal circumstances using values greater than 100ms should not be required and suggests problems with a user application or platform performance (e.g. a high priority process is using nearly 100% of CPU time).

    Note that this feature may cause very serious side effects (including not up to date locations being reported to the client application) and must NOT be normally used.

  • KLbsSpecialFeatureAllowTBFinalNetPos

    Purpose: This setting defines how the LBS subsystem handles final network position updates. There are two possibilities:

    • Setting is ESpecialFeatureOn

      A final network position may be returned to a client if it has a technology type of ETechnologyTerminal | ETechnologyAssisted OR ETechnologyNetwork | ETechnologyAssisted.

    • Setting is ESpecialFeatureOff or is not set in the repository initialisation file

      A final network position may be returned to the client only if its technology type value given by TPositionInfo::PositionMode() is ETechnologyNetwork | ETechnologyAssisted. A final network position is not returned to a client if its technology type value is ETechnologyTerminal | ETechnologyAssisted. This is the default behaviour if the setting is not set in the repository initialisation file.

    In most situations the value of this setting should be ESpecialFeatureOff.

    Values: Defined by CLbsAdmin::TSpecialFeature. See table below.

    TSpecialFeature Numerical value

    ESpecialFeatureOn

    1

    ESpecialFeatureOff

    2

  • KLbsSpecialFeatureIgnoreAccuracy

    Purpose: This setting configures LBS to either return only accurate position updates to a client application or to return all position updates including those that do not meet the position quality criteria specified by the client. There are two possibilities:

    • Setting is ESpecialFeatureOn

      Position updates that do not meet the quality criteria of the calling client are returned (as well as those that do). For full details about the effects of this setting see Location Acquisition API runtime behaviour.

    • Setting is ESpecialFeatureOff or is not set in the repository initialisation file

      This is the default behaviour if this setting is not set in the repository initialisation file. Generally only those position updates that meet the quality criteria of the calling client are returned. For full details about the effects of this setting see Location Acquisition API runtime behaviour.

    Values: Defined by CLbsAdmin::TSpecialFeature. See table below.

    TSpecialFeature Numerical value

    ESpecialFeatureOn

    1

    ESpecialFeatureOff

    2

    Important note

    If KLbsSpecialFeatureIgnoreAccuracy is set to ESpecialFeatureOn then KLbsSpecialFeatureWithholdDeliveryOfReferencePositions must be set to ESpecialFeatureOn.

  • KLbsSpecialFeatureWithholdDeliveryOfReferencePositions

    Purpose: This setting specifies if LBS should return reference positions to a client application. There are two possibilities:

    • Setting is ESpecialFeatureOn

      A reference position is not returned to a client application when a server session is opened using RPositioner::Open(RPositionServer& aPosServer, TPositionModuleId aModuleId) where aModuleId specifies a GPS module.

    • Setting is ESpecialFeatureOff or is not set in the repository initialisation file

      A reference position can be returned to a client when a location server subsession is opened using any one of the three RPositioner::Open() methods. This is the default behaviour if this setting is not set in the repository initialisation file.

    Values: Defined by CLbsAdmin::TSpecialFeature. See table below.

    TSpecialFeature Numerical value

    ESpecialFeatureOn

    1

    ESpecialFeatureOff

    2

    Important note

    If KLbsSpecialFeatureWithholdDeliveryOfReferencePositions is set to ESpecialFeatureOn then KLbsSpecialFeatureIgnoreAccuracy must be set to ESpecialFeatureOn.

  • KLbsSpecialFeatureIntermediateFutileUpdate

    Purpose: If a licensee's A-GPS module recognises that it will be unable to calculate a GPS fix (for example because it is not receiving a strong enough GPS signal in its current location) it can generate a 'futile' location update by calling MLbsLocationSourceGpsObserver::UpdateLocation() with a status code of KPositionCalculationFutile.

    If the location update happens while there is no outstanding location request from the network, the LBS subsystem normally ignores it and does not send it to the network. This is normally the correct behaviour.

    When the LBS subsystem is operating in Terminal Assisted Mode or simultaneous Terminal Assisted Mode & Terminal Based Mode (also known as Hybrid Mode), turning this setting on enables the LBS subsystem to look for 'futile' updates when there are no outstanding location requests and to return the updates to the network.

    This feature only applies when the LBS subsystem is working in Terminal Assisted Mode or Hybrid Mode.

    Values: Defined by CLbsAdmin::TSpecialFeature. See table below.

    TSpecialFeature Numerical value

    ESpecialFeatureOn

    1

    ESpecialFeatureOff

    2

Rebuilding the repository initialisation file

The binary (.cre) version of the administration repository initialisation file is generated from the text version by the centrepconv.exe conversion tool. This tool is based on the Symbian emulator and is usually found under %EPOCROOT%\epoc32\release\winscw\udeb\centrepconv.exe.

The following DOS commands copy the text version of the repository file to a location on the Symbian emulator c: drive and then run the conversion tool on it. The generated binary file is copied to the <LBS_ROOT>\LbsAdmin\group directory.

REM Set the root directory for LBS – location depends on local configuration

Set LBS_ROOT=<location of the top-level LBS directory>

REM copy the text file to the emulator c:\ drive

copy %LBS_ROOT%\LbsAdmin\data\1028224B.txt %EPOCROOT%\epoc32\winscw\c\1028224B.txt

REM run the conversion tool

pushd %EPOCROOT%\epoc32\release\winscw\udeb
centrepconv.exe –nowait –o c:\1028224B.cre c:\1028224B.txt
popd

REM copy the binary version back to the LbsAdmin directory

copy %EPOCROOT%\epoc32\winscw\c\1028224B.cre %LBS_ROOT%\LbsAdmin\group\1028224B.cre