This topic describes the LBS administration repository initialisation file.
LBS administration service overview describes the LBS administration service and the LBS Administration API.
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 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.
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.
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.
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.
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.
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.
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.
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.
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:
A client application calls RPositioner::NotifyPositionUpdate().
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.
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.
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.
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.
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.
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
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.