1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Location Based Services Administration API Settings

    15 // 

    16 //

    17 

    18 /**

    19  @file

    20  @publishedPartner

    21  @released

    22 */

    23 

    24 #ifndef LBS_ADMIN_SETTINGS_H

    25 #define LBS_ADMIN_SETTINGS_H

    26 

    27 

    28 //-------------------------------------------------------------------------------

    29 #include <lbsadmindatatypes.h>

    30 

    31 

    32 //-------------------------------------------------------------------------------

    33 // Settings IDs

    34 //-------------------------------------------------------------------------------

    35 /** No setting */

    36 const TLbsAdminSetting KLbsSettingNone							= 0x0000000000000000LL;	// Setting 0x00

    37 

    38 /** Self locate configuration for Home Network 

    39 @see CLbsAdmin::TSelfLocateService */

    40 const TLbsAdminSetting KLbsSettingHomeSelfLocate				= 0x0000000000000001LL;	// Setting 0x01

    41 

    42 /** Self locate configuration when roaming

    43 @see CLbsAdmin::TSelfLocateService */

    44 const TLbsAdminSetting KLbsSettingRoamingSelfLocate				= 0x0000000000000002LL;	// Setting 0x02

    45 		

    46 /** Positioning quality profile for the Self Locate requests.

    47 Used when the application does not specify its own criteria.

    48 Profile definitions TBD.

    49 @see TProfileId */

    50 const TLbsAdminSetting KLbsSettingQualityProfileSelfLocate		= 0x0000000000000004LL;	// Setting 0x03

    51 		

    52 /** External locate configuration for Home Network.

    53 

    54 Defines if external location requests (received from the network or from the Network Privacy API or the Privacy Request API) are processed.

    55 This setting is not checked when LBS is configured to use a Privacy Q&N Notifier (if KLbsSettingPrivacyHandler == CLbsAdmin::EPrivacyHandleByAdvancedNotifier) - requests are always sent to the Notifier.

    56 

    57 The setting may be retrieved in two ways. The default setting may be read by using 

    58 the CLbsAdmin::TExternalLocateService type when calling CLbsAdmin::Get(). By using the 

    59 TLbsAdminExtLocServicesInfo type it is possible to get both, the default setting, and the module specific settings.

    60 

    61 Module specific settings supersede the default setting.

    62 

    63 @see CLbsAdmin::TExternalLocateService 

    64 @see TLbsAdminExtLocServicesInfo

    65 @see KLbsSettingPrivacyHandler

    66 */

    67 const TLbsAdminSetting KLbsSettingHomeExternalLocate 			= 0x0000000000000008LL;	// Setting 0x04

    68 

    69 /** External locate configuration when roaming.

    70 For additional information see @see KLbsSettingHomeExternalLocate.

    71 

    72 @see CLbsAdmin::TExternalLocateService 

    73 @see TLbsAdminExtLocServicesInfo

    74 @see KLbsSettingPrivacyHandler

    75 */

    76 const TLbsAdminSetting KLbsSettingRoamingExternalLocate 		= 0x0000000000000010LL;	// Setting 0x05

    77  

    78 /** Positioning quality profile for the External Locate requests.

    79 Used when the application does not specify its own criteria.

    80 Profile definitions TBD.

    81 @see TProfileId */

    82 const TLbsAdminSetting KLbsSettingQualityProfileExternalLocate	= 0x0000000000000020LL;	// Setting 0x06

    83 

    84 /** Emergency External locate configuration for Home Network.

    85 @see CLbsAdmin::TExternalLocateService */

    86 const TLbsAdminSetting KLbsSettingHomeEmergencyLocate 			= 0x0000000000000040LL;	// Setting 0x07

    87 

    88 /** Emergency External locate configuration when roaming

    89 @see CLbsAdmin::TExternalLocateService */

    90 const TLbsAdminSetting KLbsSettingRoamingEmergencyLocate 		= 0x0000000000000080LL;	// Setting 0x08

    91 

    92 /** Send to 3rd party for Home Network 

    93 @see CLbsAdmin::TTransmitLocateService */

    94 const TLbsAdminSetting KLbsSettingHomeTransmitLocate			= 0x0000000000000100LL;	// Setting 0x09

    95 

    96 /** Send to 3rd party when roaming

    97 @see CLbsAdmin::TTransmitLocateService */

    98 const TLbsAdminSetting KLbsSettingRoamingTransmitLocate		= 0x0000000000000200LL;	// Setting 0x0A

    99 

   100 /** Positioning quality profile for the Transmit to 3rd party requests.

   101 Used when the application does not specify its own criteria.

   102 Profile definitions TBD.

   103 @see TProfileId */

   104 const TLbsAdminSetting KLbsSettingQualityProfileTransmitLocate	= 0x0000000000000400LL;	// Setting 0x0B

   105 

   106 /** GPS mode when in home network 

   107 @see CLbsAdmin::TGpsMode */

   108 const TLbsAdminSetting KLbsSettingHomeGpsMode					= 0x0000000000000800LL;	// Setting 0x0C

   109 

   110 /** GPS mode when roaming 

   111 @see CLbsAdmin::TGpsMode */

   112 const TLbsAdminSetting KLbsSettingRoamingGpsMode				= 0x0000000000001000LL;	// Setting 0x0D

   113 

   114 /** Network Protocol module(s) for Home Network.

   115 

   116 The setting may be retrieved in two ways. The Id of the default module may be read by using 

   117 the TProtocolModuleId type when calling CLbsAdmin::Get(). By using the TLbsAdminProtocolModulesInfo type 

   118 it is possible to retrieve a list of all the Protocol Modules to be loaded.

   119 

   120 @see TProtocolModuleId 

   121 @see TLbsAdminProtocolModulesInfo */

   122 const TLbsAdminSetting KLbsSettingHomeProtocolModule 			= 0x0000000000002000LL;	// Setting 0x0E

   123 

   124 /** Network Protocol module(s) when roaming.

   125 For details see @see KLbsSettingHomeProtocolModule.

   126 

   127 @see TProtocolModuleId

   128 @see TLbsAdminProtocolModulesInfo */

   129 const TLbsAdminSetting KLbsSettingRoamingProtocolModule 		= 0x0000000000004000LL;	// Setting 0x0F

   130 

   131 /** System mode configuration 

   132 @see CLbsAdmin::TLbsSystemStartMode */

   133 const TLbsAdminSetting KLbsSettingLbsSystemStartMode			= 0x0000000000008000LL;	// Setting 0x10

   134 

   135 /** Privacy settings 

   136 @see CLbsAdmin::TPrivacyTimeoutAction */

   137 const TLbsAdminSetting KLbsSettingPrivacyTimeoutAction			= 0x0000000000010000LL;	// Setting 0x11

   138 

   139 /** Privacy Handler selection

   140 @see CLbsAdmin::TPrivacyHandler */

   141 const TLbsAdminSetting KLbsSettingPrivacyHandler				= 0x0000000000020000LL;	// Setting 0x12

   142 

   143 /** LBS behaviour mode selection

   144 @see CLbsAdmin::TLbsBehaviourMode */

   145 const TLbsAdminSetting KLbsSettingBehaviourMode					= 0x0000000000040000LL;	// Setting 0x13

   146 

   147 

   148 /** Usage Logging

   149 This setting is designed to only be read on LBS system startup. 

   150 Changing it via this API while LBS is running could cause undefined behaviour. 

   151 @see CLbsAdmin::TLogger */

   152 const TLbsAdminSetting KLbsSettingLogger					= 0x0000000000080000LL;	// Setting 0x14

   153 

   154 /** Enabling LBS special features.

   155 Extra caution and full understanding of the effects is required when manipulating special features.

   156 A user MUST NOT be allowed to change them (e.g. through a UI Control Panel type application).

   157 A licensee must decide which features will be supported and fix them before a phone's release.

   158 

   159 These settings are read-only.

   160 	

   161 @see KLbsSpecialFeatureMaximumRequestDelay

   162 @see KLbsSpecialFeatureAllowTBFinalNetPos

   163 @see KLbsSpecialFeatureIgnoreAccuracy

   164 @see KLbsSpecialFeatureWithholdDeliveryOfReferencePositions

   165 @see KLbsSettingLogger

   166 @publishedPartner 

   167 @released

   168 */

   169 

   170 /** This feature allows LBS to temporarily buffer the following locations and errors:

   171 	a single Reference Location from the network,

   172 	a single Final Network Location from the network or

   173 	a single Error Code from an AGPS Module.

   174 

   175 Reason for introducing the feature:

   176 When using RPositioner from the Location Acquisition API there are very short periods of time when the LBS

   177 subsystem has no outstanding location request. This happens when an application has received an asynchronous

   178 notification (CActive::RunL()) signalling completion of a previous request, but has not yet sent a new request

   179 by calling RPositioner::NotifyPositionUpdate().

   180 	

   181 The time is defined in milliseconds and is of TLbsTimeIntervalMilliSeconds type. Acceptable values are between 0

   182 and KLbsMaximumRequestDelayMax (values above this report KErrAgrument) where 0 turns the feature OFF. Note that

   183 under normal circumstances using values greater than 100ms should not be required and suggests problems with a

   184 user application or platform performance (e.g. a high priority process is using nearly 100% of CPU time).

   185 

   186 The feature must NOT be used to accommodate for badly behaving applications 

   187 that do not reissue RPositioner::NotifyPositionUpdate() immediately.

   188 

   189 This setting is read-only, and is disabled if a value of 0 is used.

   190 

   191 @see TLbsTimeIntervalMilliSeconds

   192 @see KLbsSettingMaximumRequestDelay

   193 @see RPositioner::NotifyPositionUpdate() 

   194 @see MLbsNetworkProtocolObserver::ProcessLocationUpdate() */

   195 const TLbsAdminSetting KLbsSpecialFeatureMaximumRequestDelay	= 0x0000000000100000LL;	// Setting 0x15

   196 

   197 /** This feature enables the delivery of Terminal Based Final Network Locations to a local application.

   198 

   199 This feature may cause very serious side effects (including not up to date locations being reported

   200 to the client application) and must NOT be normally used.

   201 

   202 This setting is read-only.

   203 

   204 @see TSpecialFeature

   205 @see RPositioner::NotifyPositionUpdate()

   206 @see MLbsNetworkProtocolObserver::ProcessLocationUpdate() */

   207 const TLbsAdminSetting KLbsSpecialFeatureAllowTBFinalNetPos    = 0x0000000000200000LL;	// Setting 0x16

   208 

   209 /** This feature enables the delivery of reference positions to a local application that has opened

   210 the RPositioner by explicitly specifying the module ID. 

   211  

   212 This feature may cause very serious side effects (including not up to date locations being reported

   213 to the client application) and must NOT be normally used.

   214 

   215 This setting is read-only.

   216 

   217 @see TSpecialFeature

   218 @see RPositioner::NotifyPositionUpdate() */

   219 const TLbsAdminSetting KLbsSpecialFeatureWithholdDeliveryOfReferencePositions    = 0x0000000000400000LL;	// Setting 0x17

   220 

   221 /** Specifies the Protocol Module loading strategy. There are two loading strategies

   222 supported.

   223 Loading just one Protocol Module saves memory, but requires the LBS system to be restarted

   224 in order to load a different module (e.g. after roaming status change).

   225 Loading all (both roaming and home) Protocol Modules uses more memory, but does not require

   226 restarting LBS when roaming status changes. The latter strategy should be used if emergency call

   227 support is required (to avoid memory allocation failures). 

   228 

   229 @see TLbsAdminProtocolModuleLoadingInfo*/

   230 const TLbsAdminSetting KLbsProtocolModuleLoading    = 0x0000000000800000LL; // Setting 0x18

   231 

   232 /** The maximum number of external locate requests that can be active at any time.

   233 

   234 The value 0 is reserved for future use.

   235 The value 1 is the default, this allows only one active external locate request at a time.

   236 Values greater than 1 allow multiple requests to be handled simultaneously. Values up to KMaxTInt can be set, but memory limitations restrict the number of requests that can be supported.

   237 A privacy request will leave with error code KErrNoMemory if there is insufficient free memory to support it.

   238 

   239 If the maximum number of simultaneous requests is reached, then any further requests are rejected.

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

   241 @see MLbsPrivacyRequestObserver::OnPrivacyResponse()

   242 @see MPosVerificationObserver::HandleVerifyComplete()

   243 */

   244 const TLbsAdminSetting KLbsSettingMaximumExternalLocateRequests    = 0x0000000001000000LL; // Setting 0x19

   245 

   246 /** The time to wait after the last privacy client disconnects before shutting down LBS.

   247 Only used with the Network Privacy API and the Privacy Request API. 

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

   249 

   250 Time is specified in microseconds.

   251 

   252 @see CPosNetworkPrivacy 

   253 @see CLbsPrivacyRequest*/

   254 const TLbsAdminSetting KLbsSettingPrivacyShutdownDelay    = 0x0000000002000000LL;	// Setting 0x1A

   255 

   256 /** The maximum number of concurrent network privacy sessions allowed with the Network Privacy API.

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

   258 

   259 The value 0 disallows any network privacy sessions

   260 

   261 @see CPosNetworkPrivacy */

   262 const TLbsAdminSetting KLbsSettingPrivacyMaxNetworkSessions    = 0x0000000004000000LL;	// Setting 0x1B

   263 

   264 /** The connection timeout for sessions using the Network Privacy API.

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

   266 

   267 Time is specified in microseconds.

   268 

   269 @see CPosNetworkPrivacy */

   270 const TLbsAdminSetting KLbsSettingPrivacyConnectionTimeout    = 0x0000000008000000LL;	// Setting 0x1C

   271 

   272 /** This feature enables the withholding of the delivery of reference positions to a local application

   273 that has opened the RPositioner by explicitly specifying a GPS module ID

   274  	

   275 @see TSpecialFeature

   276 @see RPositioner::NotifyPositionUpdate 

   277 */

   278 const TLbsAdminSetting KLbsSpecialFeatureIgnoreAccuracy				= 0x0000000020000000LL;	// Setting 0x1E

   279 

   280 // leaving a space for setting added on 9.3 to make integration easier

   281 

   282 /** Privacy Timeout

   283  * Time in milliseconds that LBS will wait for a response from the privacy controller application / notifier

   284  * A value of zero means never timeout/wait forever.

   285  * @see KLbsSettingPrivacyAppTimeout

   286  * @see TLbsTimeIntervalMilliSeconds

   287  */

   288 const TLbsAdminSetting KLbsSettingPrivacyAppTimeout					= 0x000000040000000LL;	// Setting 0x1F

   289 

   290 /** 

   291 This feature enables the LBS subsystem to check for 'futile' GPS updates between location requests when LBS is working in either Terminal Assisted Mode or Simultaneous Terminal Assisted Mode & Terminal Based Mode (also known as Hybrid Mode).

   292 

   293 The LBS subsystem does not normally return a location update to the network if it occurs while there is no outstanding location request from the network. This is normally the correct behaviour.

   294 

   295 In Hybrid Mode or Terminal Assisted Mode, a licensee's GPS module may decide that there is no way of getting a GPS fix and return a 'futile' update during the session. 

   296 If the update happens while there is no outstanding network request then it is ignored and the futile update is not sent to the network.

   297 

   298 Turning this setting on enables the LBS subsystem to look for futile updates between location requests and to return the updates to the network.

   299 

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

   301 This feature may cause very serious side effects and must NOT be normally used.

   302 

   303 This setting is read-only.

   304 @see TSpecialFeature

   305 */

   306 const TLbsAdminSetting KLbsSpecialFeatureIntermediateFutileUpdate	= 0x0000000080000000LL;	// Setting 0x20

   307 

   308 /** Network induced locate configuration for Home Network.

   309 @see CLbsAdmin::TExternalLocateService */

   310 const TLbsAdminSetting KLbsSettingHomeNetworkInducedLocate			= 0x000000100000000LL;	// Setting 0x21

   311 

   312 /** Network induced locate configuration when roaming

   313 @see CLbsAdmin::TExternalLocateService */

   314 const TLbsAdminSetting KLbsSettingRoamingNetworkInducedLocate		= 0x000000200000000LL;	// Setting 0x22

   315 

   316 /** Licensee specific Set Clock Module Id.

   317 A null value means that a default, internal implementation should be used.

   318 @see TLbsSetClockModuleId */

   319 const TLbsAdminSetting KLbsSettingSetClockModule 				= 0x0800000000000000LL;	// Setting 0x3C

   320 

   321 /** Automatic clock adjustment interval in microseconds.

   322 The value defines the time between consecutive attempts 

   323 to automatically adjust the clock.

   324 Relevant only if automatic clock adjustment is enabled.

   325 @see CLbsAdmin::KLbsSettingClockAdjust

   326 @see CLbsAdmin::KLbsSettingClockAdjustThreshold */

   327 const TLbsAdminSetting KLbsSettingClockAdjustInterval			= 0x1000000000000000LL;	// Setting 0x3D

   328 

   329 /** Automatic clock adjustment threshold in microseconds.

   330 If the difference between the system UTC time and the

   331 GPS based UTC time is less than the threshold then the

   332 system clock is not being adjusted.

   333 Relevant only if automatic clock adjustment is enabled.

   334 @see CLbsAdmin::KLbsSettingClockAdjust 

   335 @see TTimeIntervalMilliSeconds */

   336 const TLbsAdminSetting KLbsSettingClockAdjustThreshold			= 0x2000000000000000LL;	// Setting 0x3E

   337 

   338 /** Allow the system clock to be adjusted manually (synchronised with GPS on user demand).

   339 @see CLbsAdmin::TClockAdjust */

   340 const TLbsAdminSetting KLbsSettingAllowManualClockAdjust		= 0x4000000000000000LL; // Setting 0x3F

   341 

   342 /** Synchronise the handset clock with the time obtained from GPS.

   343 @see CLbsAdmin::TClockAdjust */

   344 const TLbsAdminSetting KLbsSettingClockAdjust					= 0x8000000000000000LL;	// Setting 0x40

   345 

   346 

   347 #endif //LBS_ADMIN_SETTINGS_H