This document explains how to get and set LBS Administration settings at runtime.
This document describes how to use the LBS administration service via the LBS Administration API.
LBS Administration Service Overview describes the LBS administration service and the LBS Administration API.
Client applications use the LBS Administration API in two ways:
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 administration settings.
This section describes how client applications use the LBS Administration API to get and set LBS administration settings. Examples are given for the different types of administration settings categories.
Location request settings
These setting are used to turn location requests on and off. Settings exist for Mobile Originated Location Requests (MO-LR), Mobile Terminated Location Requests (MT-LR) and Transfer Location to 3rd Party Requests (X3P). The code example below shows how to:
Turn on MO-LR (self locate) in the home network and when roaming.
CLbsAdmin::TSelfLocateService defines the constants used to configure MO-LR.
#include <lbsadmin.h> ... CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); TInt err = KErrNone; // Turn on MO-LR in home network & when roaming. err = admin->Set(KLbsSettingHomeSelfLocate, CLbsAdmin::ESelfLocateOn); err = admin->Set(KLbsSettingRoamingSelfLocate, CLbsAdmin::ESelfLocateOn); if (err != KErrNone) { // Handle error ... } ...
Turn on MT-LR (external locate) in the home network and off when roaming. Note that Emergency MT-LR is unaffected and is always on.
CLbsAdmin::TExternalLocateService defines the constants used to configure MT-LR.
... // Turn on external locate in home network. Turn off when roaming. err = admin->Set(KLbsSettingHomeExternalLocate, CLbsAdmin::EExternalLocateOn); err = admin->Set(KLbsSettingRoamingExternalLocate, CLbsAdmin::EExternalLocateOff); if (err != KErrNone) { // Handle error ... } ...
Turn on X3P (transfer to third party) in the home network and off when roaming.
CLbsAdmin::TTransmitLocateService defines the constants used to configure X3P.
... // Turn on transfer to 3rd party locate. Turn off when roaming. err = admin->Set(KLbsSettingHomeTransmitLocate, CLbsAdmin::ETransmitLocateOn); err = admin->Set(KLbsSettingRoamingTransmitLocate, CLbsAdmin::ETransmitLocateOff); if (err != KErrNone) { // Handle error ... } ...
Get the location request settings
... // Get some settings... CLbsAdmin::TSelfLocateService selfLocate; CLbsAdmin::TExternalLocateService externalLocate; CLbsAdmin::TTransmitLocateService transmitLocate; err = admin->Get(KLbsSettingHomeSelfLocate, selfLocate); err = admin->Get(KLbsSettingHomeExternalLocate, externalLocate); err = admin->Get(KLbsSettingHomeTransmitLocate, transmitLocate); if (err != KErrNone) { // Handle error ... } CleanupStack::PopAndDestroy();
Quality profile settings
Quality profiles define the quality of position required by a LBS location request. They are used when a client makes a LBS location request without specifying any position quality criteria.
Quality profiles are defined in the file lbsprofile.ini. The file is located at <rom_drive>:\private\10282253\lbs\lbsprofile.ini or <system_drive>:\private\10282253\lbs\lbsprofile.ini (the file location is dependent on the licensee OS build and configuration process).
An example quality profile file is shown below in which two quality profiles defined. Each quality profile has a unique ID defined by the value ProfileID.
# lbsprofile.ini # Quality Profiles for LBS services # [1] ProfileID= 0 MaxTime= 130 HorizontalAccuracy= 50 VerticalAccuracy= 1000 [2] ProfileID= 1 MaxTime= 120 HorizontalAccuracy= 20 VerticalAccuracy= 1000
The default quality profiles for use by MO-LR, MT-LR and X3P are defined in the LBS administration repository initialisation file.
The code example below shows how to use the LBS Administration API to change the quality profile for MO-LR.
#include <lbsadmin.h> ... CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); TLbsQualityProfileId selfProfileId; TLbsQualityProfileId newProfileId = 1; TInt err = KErrNone; // Set quality profile for MO-LR err = admin->Get(KLbsSettingQualityProfileSelfLocate, selfProfileId); if (err != KErrNone) { // Handle error ... } if (selfProfileId != 1) { err = admin->Set(KLbsSettingQualityProfileSelfLocate, newProfileId); if (err != KErrNone) { // Handle error ... } } CleanupStack::PopAndDestroy();
GPS operation mode settings
These settings configure the mode of operation of GPS in the home network and when roaming.
CLbsAdmin::TGpsMode defines the constants used to configure GPS.
The code example below shows how to use the LBS Administration API to configure GPS to calculate position using assistance data from the network. LBS tries to get assistance data from the network to calculate the location, but if this data is not available then LBS attempts to get a GPS fix without it.
#include <lbsadmin.h> ... CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); TInt err = KErrNone; // 1. Use assisted mode GPS in home network and when roaming err = admin->Set(KLbsSettingHomeGpsMode, CLbsAdmin::EGpsPreferTerminalBased); err = admin->Set(KLbsSettingRoamingGpsMode, CLbsAdmin::EGpsPreferTerminalBased); // 2. Get home GPS mode setting CLbsAdmin::TGpsMode gpsMode; err = admin->Get(KLbsSettingHomeGpsMode, gpsMode); if (err != KErrNone) { // Handle error ... } CleanupStack::PopAndDestroy();
Network protocol module setting
This setting gets and sets the UID of the network protocol module that is used in both the home network and when roaming.
Note that the value of the UID must be that of the ECom protocol module implementation as defined by implementation_uid in the ECom resource file.
The code example below shows how to use the LBS Administration API to set the network protocol module.
#include <lbsadmin.h> ... CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); TInt err = KErrNone; TUid modUid; // Get the UID of licensee network protocol module ECom plug-in ... // Set the network protocol module err= admin->Set(KLbsSettingHomeProtocolModule, modUid); if (err != KErrNone) { // Handle error ... } CleanupStack::PopAndDestroy();
Note that changing the KLbsSettingHomeProtocolModule setting requires a restart of the LBS subsystem. This may require a reboot of the mobile device for the change to take effect, but not if the LBS subsystem is configured to start in transient mode, as is the case in Standalone Privacy Mode.
Privacy notifier settings
These settings are used to:
Configure LBS to use a privacy controller or privacy notifiers
CLbsAdmin::TPrivacyHandler defines the constants that configure LBS to use a privacy controller or privacy notifiers.
Set the action to take on timeout of a MT-LR privacy request
CLbsAdmin::TPrivacyTimeoutAction defines the constants that configure the action to take on timeout.
Note that setting this to reject MT-LR does not reject Emergency MT-LR.
The code example below shows how to use the LBS Administration API to configure LBS to use privacy notifiers and to reject privacy requests on timeout.
#include <lbsadmin.h> ... CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); TInt err = KErrNone; // Set LBS to use privacy notifiers err = admin->Set(KLbsSettingPrivacyHandler, CLbsAdmin::EPrivacyHandleByNotifier); // Set LBS to reject privacy requests on timeout err = admin->Set(KLbsSettingPrivacyTimeoutAction, CLbsAdmin::EPrivacyTimeoutReject); if (err != KErrNone) { // Handle error ... } CleanupStack::PopAndDestroy();
Note that changing the KLbsSettingPrivacyHandler setting requires a restart of the LBS subsystem. This may require a reboot of the mobile device for the change to take effect, but not if the LBS subsystem is configured to start in transient mode, as is the case in Standalone Privacy Mode.
GPS set clock module settings
These settings are used to:
Configure LBS to allow the system clock to be synchronised with GPS
CLbsAdmin::TClockAdjust defines the constants that configure system clock synchronisation.
LBS can be configured to allow fully automatic system clock synchronisation. This means the system clock is synchronised with GPS at regular intervals.
The code example below shows how to turn on automatic clock adjustment.
#include <lbsadmin.h> ... TInt err = KErrNone; CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); // Configure LBS to allow automatic clock synchronisation err = admin->Set(KLbsSettingClockAdjust, CLbsAdmin::EClockAdjustOn); if (err != KErrNone) { // Handle error ... } ...
Specify the UID of the GPS set clock plug-in
A GPS set clock plug-in is an ECom plug-in that allows LBS to set the system time on the mobile device.
LBS contains a default implementation of a set clock plug-in that sets the system time by calling User::SetUTCTime(). It is only necessary to change the KLbsSettingSetClockModule setting if a licensee wishes to use some other means to set the system time. Setting KLbsSettingSetClockModule to 0 specifies that LBS will use the default plug-in.
If KLbsSettingSetClockModule is set to some value other than 0, it must be set to the UID of a licensee set clock plug-in. The UID must be that of the ECom implementation as defined by implementation_uid in the ECom resource file.
The code example below shows setting the clock module to a licensee set clock plug-in UID.
... TUid KLicenseeClockModule; // Get the licensee clock module ID // (only if licensee uses a module other than the default) ... // Set UID of GPS Clock module err = admin->Set(KLbsSettingSetClockModule, KLicenseeClockModule); if (err != KErrNone) { // Handle error ... } ...
Note that changing the KLbsSettingSetClockModule setting requires a reboot of the mobile device for the change to take effect.
Set the clock adjustment interval
This is the time in milliseconds between system clock updates. This setting is only used if LBS is configured to allow automatic system clock adjustment (see 1 above).
... TUint KClockInterval(604800000); // 7 days in milliseconds // Set the clock adjustment interval err = admin->Set(KLbsSettingClockAdjustInterval, KClockInterval); if (err != KErrNone) { // Handle error ... } ...
Set the clock adjustment threshold
This is a time in milliseconds. The system clock is adjusted if the time difference between it and the GPS clock is greater than this threshold time. This setting is only used if LBS is configured to allow automatic system clock adjustment (see 1 above).
... TUint KClockThreshold(1000); // 1 second err = admin->Set(KLbsSettingClockAdjustThreshold, KClockInterval); if (err != KErrNone) { // Handle error ... } ...
An application can reset administration settings to the defaults specified in the administration settings initialisation file by calling CLbsAdmin::ResetToDefault().
#include <lbsadmin.h> ... TInt err = KErrNone; CLbsAdmin* admin = CLbsAdmin::NewL(); CleanupStack::PushL(admin); err = admin->ResetToDefault(); if (err != KErrNone) { // Handle error ... } CleanupStack::PopAndDestroy();
Applications can register to receive notifications of changes to LBS administration settings. To create a class to receive notifications of LBS administration settings changes, a developer:
Defines an observer class derived from MLbsAdminObserver
#include <lbsadmin.h> class CLbsAdminObserver : public MLbsAdminObserver { public: static CLbsAdminObserver* NewL(); // From MLbsAdminObserver void OnSettingUpdateEvent(TInt aError, const TLbsAdminSetting& aSetting); protected: CLbsAdminObserver(); ~CLbsAdminObserver(); void ConstructL(); private: CLbsAdmin* iLbsAdmin; TLbsAdminSettingGroup iGroup; };
Defines the types of administration settings changes of interest to the observer by creating a TLbsAdminSettingGroup bitmask.
The code example below shows the observer class constructor in which a TLbsAdminSettingGroup bitmask is defined.
CLbsAdminObserver::CLbsAdminObserver() { iGroup = KLbsSettingHomeSelfLocate | KLbsSettingRoamingSelfLocate | KLbsSettingHomeExternalLocate | KLbsSettingRoamingExternalLocate | KLbsSettingHomeTransmitLocate | KLbsSettingRoamingTransmitLocate; }
Writes an implementation of the MLbsAdminObserver::OnSettingUpdateEvent() method. This method is called when there is a change in one of the administration settings defined in the bitmask (see point 2 above).
The code example below shows a partial method implementation in which the value of the aSetting parameter value is checked. Once the value of aSetting is known, the value of the setting is obtained by calling CLbsAdmin::Get() with the appropriate parameters.
void CLbsAdminObserver::OnSettingUpdateEvent(TInt aError, const TLbsAdminSetting& aSetting) { if (aSetting == KLbsSettingHomeSelfLocate) { // Setting for MO-LR in home network has changed // Get the new setting TInt err; CLbsAdmin::TSelfLocateService selfLocate; err = iLbsAdmin->Get(KLbsSettingHomeSelfLocate, selfLocate); if (err != KErrNone) { // Handle error ... } } // And similar for other TLbsAdminSetting types in the TLbsAdminSetting bitmask ... }
Registers an observer object to receive notification of status change events by calling CLbsAdmin::NewL() with the observer object and a TLbsAdminSettingGroup bitmask as parameters. The code example below shows this in the NewL() method of the observer class.
CLbsAdminObserver* CLbsAdminObserver::NewL() { CLbsAdminObserver* self = new(ELeave)CLbsAdminObserver(); CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(); return self; } void CLbsAdminObserver::ConstructL() { iLbsAdmin = CLbsAdmin::NewL(*this, const_cast<TLbsAdminSettingGroup&>(iGroup)); }
An application can stop receiving notification of administration settings changes by calling CLbsAdmin::ClearNotificationMask().
An application can change the administration settings changes for which it receives notification by calling CLbsAdmin::SetNotificationMaskL().
The code example below shows the use of these methods to receive notification of GPS mode settings changes.
iLbsAdmin->ClearNotificationMask(); // Change the notification mask to get changes to GPS mode iGroup = KLbsSettingHomeGpsMode | KLbsSettingRoamingGpsMode; iLbsAdmin->SetNotificationMaskL(iGroup);
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.