S60 5.2 SUPL Settings API |
DN0756875 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.0 |
29.06.2009 |
Approved |
|
![]() |
Type | Class | Change |
---|---|---|
New public method | CSuplSettings | TInt GetTriggerParams(RPointerArray<CTriggerParams>& aParamValues ) const |
New public method | CSuplSettings |
TInt GetTriggerParams( TInt aSessionId, CTriggerParams*& aParamValues ) const |
New public method | CSuplSettings | TInt SetNotificationStatus( TInt aSessionId,TBool aTriggerNotificationStatus) |
New public method | CSuplSettings | TInt CancelTriggerSession( TInt aSessionId ) |
Type | Class | Change |
---|---|---|
New public method | CTriggerParams | TInt Set() |
New public method | CTriggerParams | TInt Get() |
Type | Class | Change |
---|---|---|
New constant | const TInt KMaxTriggerSessionNameLen=256; |
![]() |
SUPL Settings API is intended for applications or components which need to read and update SUPL settings and listen to SUPL settings changes. SUPL Settings API provides a way to retrieve IMSI and generating HSLP address from IMSI. Client can also read/store active SUPL trigger session information using this API.
![]() |
SUPL Settings API can be used to read and change SUPL settings and to listen to changes in SUPL settings. This API is meant for clients who want to read/change SUPL settings and listen to changes in SUPL settings.
SUPL settings contain following information:
HSLP Properties | HSLP properties refers to properties of Home SUPL Location Platform which includes such as protocol version supported, TLS support etc. |
IMSI | IMSI is the mobile subscriber identity. |
SUPL Usage | SUPL Usage indicates whether user should be notified or not before using SUPL. |
Fallback | Fallback is used for storing information about whether fallback can happen or not if the connection/session with one of the HSLP fails. |
Fallback timer | Fallback timer indicate for how long fallback can happen. This is represented in seconds. |
Active SUPL triggering session parameters | It indicates the information about ongoing SUPL triggering sessions. Parameter like "Notification status" can be configured by Settings API client. |
HSLP Properties refers to the different parameters pertaining to HSLP. There can be any number of HSLP properties present in SUPL settings.
The currently active IMSI value is obtained from the system during SUPL Settings initialization time. The IMSI value obtained during initialization can also be retrieved using SUPL Settings API.
The IMSI value stored in the SUPL settings can be used by the client to check whether IMSI has changed and to generate HSLP address. For example, the HSLP address can be generated from IMSI if HSLP address read from SUPL settings is empty or not valid.
The SUPL Usage value indicates whether user intervention is required before using SUPL or not. By default SUPL Usage is set to "Always ask". If SUPL Usage has value indicating automatic, SUPL can be used to make location request or to get assistance data. If SUPL Usage has value indicating automatic in home network, a confirmation dialog is shown before using SUPL when the terminal is roaming. If SUPL Usage has value indicating always ask, a confirmation dialog is shown before using SUPL. If SUPL Usage has value indicating disabled, SUPL cannot be used at all.
The fallback value indicates whether fallback to next server in the list can happen or not if SUPL session with one of the server fails. By default fallback is enabled.
The fallback timer indicates for how long the fallback can happen.
Session ID | Unique Session identifier |
Session Name | Session/Service Name |
Notification Presence | Parameter to indicate whether notification is present or not for a given session |
Notification Status | Indicates whether notification needs to be shown or not after every trigger fired for a given periodic session |
Trigger Type | Indicates whether the trigger is periodic trigger or area event trigger |
Request Type | Indicates whether the request is terminal initiated or network initiated |
Number of Outstanding triggers | Indicates number of outstanding triggers. This is valid only if the trigger type is periodic triggers. |
Interval | Indicates interval between the triggers. This is valid only if the trigger type is periodic triggers. It's unit is seconds. |
HSLP Properties contains:
HSLP Address | HSLP address is a Fully Qualified Domain Name (FQDN) of Home SUPL Location Platform. More details about the HSLP can be found in references [1] and [2]. |
IAP Name | IAP name refers to the Access Point which the terminal can use to access the HSLP over the Internet. |
SLP Enabled | Indicates whether HSLP is enabled or not. The SLP can be used only if it is enabled. |
Usage in Home network | Indicates whether the server can be used in home network or not. |
Remove SLP when SIM changes | This indicates whether HSLP entries can be removed or not when SIM change happens. if this is enabled, the SLP entry in the SUPL settings will be removed if there is a SIM change |
Editable | This indicates whether server entries can be modified by UI application or not. |
![]() |
The use cases of SUPL Settings API are:
Get/Set SUPL settings
Change Priority
Listening to SUPL Settings changes
Using IMSI obtained during initialization
![]() |
![]() |
![]() |
One of the main use cases of SUPL Settings API is to read and change server parameters, SUPL usage and fallback in SUPL Settings. SUPL Settings API can be used to change either one parameter or all the parameters in the SUPL Settings storage.
![]() |
In SUPL Settings server properties consists of different parameters which are used during connection establish time. A client may add new server and its properties in SUPL Settings.
The following diagram illustrates the steps involved in changing server properties using SUPL Settings API.
The following code snippet illustrates how to add new server entry to SUPL settings using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Method to set the SUPL Settings parameters with // example values void AddNewServerEntry(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } // Method to add new server entry to SUPL settings with // example values void CMySettingsClientClass::AddNewServerEntry() { CServerParams *params; TInt64 slpId; params = CServerParams::NewL(); params->Set("suplserver.com", "airtel"); err = iSettings->AddNewServer(params, slpId); if (err != KErrNone) { // Error has occured } delete params; }
![]() |
In SUPL Settings server properties consists of different parameters which are used during connection establish time. A client may change server properties of any server in SUPL Settings.
The following diagram illustrates the steps involved in changing server properties using SUPL Settings API.
The following code snippet illustrates how to add new server entry to SUPL settings using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Method to set the SUPL Settings parameters with // example values void AddNewServerEntry(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } // Change properties of existing server entry with // example values void CMySettingsClientClass::ChangeServerEntry() { CServerParams *params; TInt64 slpId; params = CServerParams::NewL(); err = iSettings->GetSlpInfoAddress("suplserver.com", params); if (err != KErrNone) { // Error has occured } RBuf hslpAddr; RBuf iapName; hslpAddr.Create(KMaxHSLPAddrLen); iapName.Create(KMaxIAPLen); TInt64 slpId; TBool enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag; TInt errParams = params->Get(slpId, hslpAddr, iapName, enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag); if (errParams != KErrNone) { // Error has occured } // Change server address and few flags and write back to settings _LIT8(KHslp, "suplserver.com"); hslpAddr.Copy(KHslp); errParams = params->Set(hslpAddr, iapName, enabledFlag, EFalse, EFalse, editFlag, slpId); if (errParams != KErrNone) { // Error has occured } err = iSettings->SetAllParameter(params); if (err != KErrNone) { // Error has occured } hslpAddr.Close(); iapName.Close(); delete params; }
![]() |
A client may change SUPL Usage in SUPL Settings. If SUPL Usage has value indicating automatic, SUPL can be used to make location request or to get assistance data. If SUPL Usage has value indicating automatic in home network, a confirmation dialog is shown before using SUPL when the terminal is roaming. If SUPL Usage has value indicating always ask, a confirmation dialog is shown before using SUPL. If SUPL Usage has value indicating disabled, SUPL cannot be used at all. Changing SUPL Usage does not require initialization of SUPL Settings.
The following diagram illustrates the steps involved in changing SUPL Usage using SUPL Settings API.
The following code snippet illustrates how to set SUPL usage using SUPL Settings API.
#include <epos_csuplsettings.h> class CMySettingsClientClass : public CActive { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Helper methods // Method to set the SUPL usage with example values void SetSuplUsageL(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } // Method to set the SUPL Usage with example values void CMySettingsClientClass::SetSuplUsageL() { // Set SUPL Usage to "Automatic" ret = iSettings->SetSuplUsage(CSuplSettings::ESuplUsageAutomatic); if (ret != KErrNone) { // Error has occured, handle it } }
![]() |
A client may change fallback SUPL Settings. If fallback is enabled, then during fallback will happen to next server in the list if connection fails to the address specified or to the default server. Changing fallback does not require initialization of SUPL Settings.
The following diagram illustrates the steps involved in changing fallback using SUPL Settings API.
The following code snippet illustrates how to change fallback using SUPL Settings API.
#include <epos_csuplsettings.h> // Example code to read fallback from SUPL settings // and disable fallback if it is enabled void CMySettingsClientClass::ChangeFallBack() { TInt err; TBool fallback; err = iSettings->GetFallBack(fallBack); if (err != KErrNone) { // Error has occured } // Check if fallback is enabled. If so disable it if (fallback) { err = iSettings->SetFallBack(EFalse); if (err != KErrNone) { // Error has occured } } }
![]() |
A client may retrieve server properties from SUPL Settings using SUPL Settings API. Server properties contains information which can be used to establish SUPL Session, see reference document [1] and [2].
The following diagram illustrates the steps involved in retrieving server properties based on server address using SUPL Settings API.
The following code snippet illustrates how to get server properties based on server address from SUPL Settings using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> // Get server properties from SUPL settings based // on server address void CMySettingsClientClass::GetServerEntry() { CServerParams *params; TInt64 slpId; params = CServerParams::NewL(); err = iSettings->GetSlpInfoAddress("suplserver.com", params); if (err != KErrNone) { // Error has occured } RBuf hslpAddr; RBuf iapName; hslpAddr.Create(KMaxHSLPAddrLen); iapName.Create(KMaxIAPLen); TInt64 slpId; TBool enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag; TInt errParams = params->Get(slpId, hslpAddr, iapName, enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag); if (errParams != KErrNone) { // Error has occured } hslpAddr.Close(); iapName.Close(); delete params; }
![]() |
A client may retrieve SUPL Usage from SUPL Settings. SUPL Usage indicates whether user intervention is required or not before using SUPL. The following diagram illustrates the steps involved in retrieving SUPL Usage using SUPL Settings API.
The following code snippets illustrates how to get SUPL Usage using SUPL Settings API.
#include <epos_csuplsettings.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Helper methods // Method to get the SUPL usage void GetSuplUsage(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } // Method to set the SUPL Usage with example values void CMySettingsClientClass::GetSuplUsage() { CSuplSettings::TSuplSettingsUsage usage; TInt ret = iSettings->GetSuplUsage(usage); if (ret != KErrNone) { //Handle Error } }
![]() |
A client may retrieve parameters of all active trigger sessions or parameters of a given session from SUPL Settings.
The following code snippet illustrates how to get parameters of all active trigger sessions and parameter of a given session using SUPL Settings API.
#include <epos_csuplsettings.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Helper methods // Method to get all session params void GetAllSessionParamsL(); // Method to get a session params void GetSessionParamsL(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } void CMySettingsClientClass::GetAllSessionParamsL() { RPointerArray< CTriggerParams > paramValues; TInt err = iSettings->GetTriggerParams( paramValues ); if( KErrNone != err ) { // Handle error } paramValues.ResetAndDestroy(); paramValues.Close(); } void CMySettingsClientClass::GetSessionParamsL() { CTriggerParams* paramValues=CTriggerParams::NewL(); //Get parameters of a session with session id=5 TInt err = iSettings->GetTriggerParams( 5,paramValues ); if( KErrNone != err ) { // Handle error } delete paramValues; }
SUPL trigger session parameters are encapsulated in CTriggerParams class. Following code snippet shows how to retrieve each individual information in CTriggerParams class.
void CMySettingsClientClass::RetrieveParams() { TUint sessionId; TBool notificationPresent; TBool triggerNotificationStatus; CTriggerParams::TTriggerType triggerType; CTriggerParams::TRequestType requestType; TUint outstandingTrigger; TUint interval; HBufC* sessionName = HBufC::NewL( KMaxTriggerSessionNameLen ); // "params" is CTriggerParams object containing session information TInt err = params->Get(sessionId,sessionName->Des(),notificationPresent,triggerNotificationStatus, triggerType,requestType,outstandingTrigger,interval ); if( KErrNone != err ) { // Handle error } delete sessionName; }
![]() |
Client can set/reset "Notification Status" attribute for a given session.
The following code snippet illustrates how to set notification status attribute for a given session using SUPL Settings API.
#include <epos_csuplsettings.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Helper methods // Method to set notification status void SetNotificationStatus(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } void CMySettingsClientClass::SetNotificationStatus() { // Example value for session ID TInt sessionId = 3; // Set notification status for a given session to EFalse TInt err = iSettings->SetNotificationStatus(sessionId,EFalse); if( KErrNone != err ) { // Handle error } }
![]() |
The following code snippet illustrates how to cancel/remove ongoing SUPL triggered session.
#include <epos_csuplsettings.h> class CMySettingsClientClass : public CBase { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); public: // Helper methods // Method to cancel active session void CancelSession(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } void CMySettingsClientClass::CancelSession() { // Example value for session ID TInt sessionId = 3; TInt err = iSettings->CancelTriggerSession(sessionId); if( KErrNone != err ) { // Handle error } }
![]() |
Clients using SUPL Settings may want to listen to SUPL Settings change events. To receive SUPL Settings change events, client has to derive its class from MSuplSettingsObserver and implement the HandleSuplSettingsChangeL() method. The client has to invoke the SetObserverL() method of CSuplSettings to start listening to changes. If any of the values changes in the SUPL Settings storage, the client is informed about it. Depending on the type of event received, either communication parameter change event or SUPL Usage change event, the client can read the new values from the SUPL Settings storage. The client can invoke the RemoveObserver() method of CSuplSettings to stop listening to SUPL Settings changes.
Code Example
The following code snippet illustrates how the client can listen for SUPL Settings events using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMyEventListener : public CBase, public MSuplSettingsObserver { public: // Constructors and destructor ... void HandleSuplSettingsChangeL(); private: // Data CSuplSettings* iSettings; }; void CMyEventListener::ConstructL() { iSettings = CSuplSettings::NewL(); } CMyEventListener::~CMyEventListener() { delete iSettings; } void CMyEventListener::StartObservingL() { TInt ret = iSettings->SetObserverL(*this); if (ret != KErrNone) { // Handler error } } void CMyEventListener::StopObserving() { iSettings->RemoveObserver(); } class CMyEventListener : public CBase, public MSuplSettingsObserver { public: // Constructors and destructor ... void HandleSuplSettingsChangeL(); private: // Data CSuplSettings* iSettings; }; void CMyEventListener::ConstructL() { iSettings = CSuplSettings::NewL(); } CMyEventListener::~CMyEventListener() { delete iSettings; } void CMyEventListener::StartObservingL() { TInt ret = iSettings->SetObserverL(*this); if (ret != KErrNone) { // Setting of observer has failed. // SUPL settings change events will not be // received. Leave. User::Leave(ret); } } void CMyEventListener::StopObserving() { iSettings->RemoveObserver(); } void CMyEventListener::HandleSuplSettingsChangeL(TSuplSettingsEventType aEvent) { // Read the SUPL settings again because something has been changed. RBuf hslpAddr, iapName, imsi; hslpAddr.CreateL(KMaxHSLPAddressLength); iapName.CreateL(KMaxIAPName); imsi.CreateL(KMaxIMSILength); CSuplSettings::TSuplSettingsChangedBy changedBy; CSuplSettings::TSuplSettingsUsage suplUsage; TInt err; if (aEvent == ESuplSettingsEventCommParameterChange) { // Settings has changed, read settings } else if (aEvent == ESuplSettingsEventSuplUsageChange) { // SUPL Usage has changed } else if (aEvent == ESuplSettingsEventServerAdd) { // New server has been added to SUPL settings } else if (aEvent == ESuplSettingsEventServerDelete) { // Server has been deleted SUPL settings } else if (aEvent == ESuplSettingsEventServerUpdate) { // Server has been updated SUPL settings } hslpAddr.Close(); iapName.Close(); imsi.Close(); }
Clients using SUPL Settings may also want to listen to SUPL Session parameter change events. To receive SUPL Session parameter change events, client has to derive its class from MSuplSessionObserver and implement the HandleSuplSessionChangeL() method. The client has to invoke the SetSessionObserverL() method of CSuplSettings to start listening to changes. If any of the values changes in the SUPL Settings Session storage, the client is informed about it. Depending on the type of event ( addition, updation or deletion ) received,the client can read the new values from the SUPL Settings Session storage. The client can invoke the RemoveSessionObserver() method of CSuplSettings to stop listening to SUPL Session parameter changes.
The following code snippet illustrates how the client can listen for SUPL Session parameter change events using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_msuplsessionobserver.h> class CMyEventListener : public CBase, public MSuplSessionObserver { public: // Constructors and destructor ... void HandleSuplSessionChangeL( TSuplSessionEventType aEvent, TInt aSessionId ); private: // Data CSuplSettings* iSettings; }; void CMyEventListener::ConstructL() { iSettings = CSuplSettings::NewL(); } CMyEventListener::~CMyEventListener() { delete iSettings; } void CMyEventListener::StartObservingL() { TInt ret = iSettings->SetSessionObserverL(*this); if (ret != KErrNone) { // Handler error } } void CMyEventListener::StopObserving() { iSettings->RemoveSessionObserver(); } void CMyEventListener::HandleSuplSessionChangeL( TSuplSessionEventType aEvent,TInt aSessionId ) { // Read the SUPL trigger Session parameters again because something has been changed for session with ID=aS essionId. // Identify the type of event if (aEvent == ESuplSessionDBAddEvent ) { // New session has been added } else if (aEvent == ESuplSessionDBDeleteEvent) { // Session removed } else if (aEvent == ESuplSessionDBUpdateEvent) { // Session parameters updated } else { // Unspecified event } }
![]() |
The order of server entries in SUPL settings is priority of servers.
![]() |
The priority of server in SUPL settings can be either increased or decreased. The following diagram illustrates the steps involved in changing priority using SUPL Settings API.
The following code snippet illustrates how to change priority using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> // Change priority of server to increase priority void CMySettingsClientClass::ChangePriorityOfServer() { CServerParams *params; TInt64 slpId; params = CServerParams::NewL(); err = iSettings->GetSlpInfoAddress("suplserver.com", params); if (err != KErrNone) { // Error has occured } RBuf hslpAddr; RBuf iapName; hslpAddr.Create(KMaxHSLPAddrLen); iapName.Create(KMaxIAPLen); TInt64 slpId; TBool enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag; TInt errParams = params->Get(slpId, hslpAddr, iapName, enabledFlag, simChangeFlag, usageInHomeNwFlag, editFlag); if (errParams != KErrNone) { // Error has occured } err = iSettings->ChangePriority(slpId, 2, ETrue) hslpAddr.Close(); iapName.Close(); delete params; }
![]() |
During initialization, currently active IMSI is obtained from the system. Using SUPL Settings API, this IMSI value can be used for different purpose such as generating HSLP address from IMSI, to check whether currently active IMSI is different from the IMSI present in SUPL Settings, etc.
![]() |
The IMSI obtained during initialization can be retrieved using SUPL Settings API. The following diagram illustrates the steps involved in getting IMSI using SUPL Settings API.
The following code snippet illustrates how to initialize the settings object, how to retrieve the IMSI obtained during initialization using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMySettingsClientClass : public CActive { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); // InitializeSettings Method void InitializeSettings(); protected : // From CActive // Overriding RunL void RunL(); // Overriding RunError TInt RunError(TInt aError); // Overriding DoCancel void DoCancel(); public: // Helper methods // Method to retrive the IMSI obtained during initialization void GetImsi(); private: // Data // SUPL Settings CSuplSettings* iSettings; RBuf iImsi; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); iImsi.CreateL(KMaxIMSILen); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { iImsi.Close(); delete iSettings; } // Cancellation method for the active object void CMySettingsClientClass::DoCancel() { // This method gets invoked only when // the object is active iSettings->CancelInitialize(); } // Active object RunL void CMySettingsClientClass::RunL() { TInt err = iStatus.Int(); if (err != KErrNone) { // Handle error. Initialization has failed, // client cannot retrieve the IMSI. User::Leave(err); } } // Active object RunError TInt CMySettingsClientClass::RunError(TInt aError) { // Leave has happened in RunL and ignored return KErrNone; } // Method to initialize SUPL Settings void CMySettingsClientClass::InitializeSettings() { iSettings->Initialize(iStatus); SetActive(); } // Method that get the IMSI obtained during initialization. // The IMSI value is provided by SUPL Settings API void CMySettingsClientClass::GetImsi() { TInt err = iSettings->GetImsi(iImsi); if (err != KErrNone) { // Handle error } }
![]() |
Using IMSI obtained during initialization HSLP address can be generated using SUPL Settings API. This HSLP address can be used during SUPL session establishment, see reference document [6] and [7]. HSLP address is provided in the FQDN format and can have maximum size of 256 bytes. The client must allocate enough memory to hold the HSLP address. HSLP address can also be generated from IMSI, for example, if HSLP address read from SUPL Settings is empty or not valid. The generated HSLP is in the FQDN format and looks like "h-slp.mncXXX.mccYYY.3gppnetwork.org" where XXX and YYY values for MNC and MCC extracted from IMSI.
The following diagram illustrates the steps involved in generating HSLP address from IMSI using SUPL Settings API.
The following code snippets illustrates how to generate HSLP address from IMSI using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMySettingsClientClass : public CActive { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); // InitializeSettings Method void InitializeSettings(); protected : // From CActive // Overriding RunL void RunL(); // Overriding RunError TInt RunError(TInt aError); // Overriding DoCancel void DoCancel(); public: // Helper methods // Method to invoke the generation of HSLP Address // from the IMSI obtained during initialization void GenerateHSLPAddress(); private: // Data // SUPL Settings CSuplSettings* iSettings; // For HSLP address generation RBuf iNewHslpAddr; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); iNewHslpAddr.CreateL(KMaxHSLPAddrLen); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { iNewHslpAddr.Close(); delete iSettings; } // Cancellation method for the active object void CMySettingsClientClass::DoCancel() { // This method gets invoked only when // the object is active iSettings->CancelInitialize(); } // Active object RunL void CMySettingsClientClass::RunL() { TInt err = iStatus.Int(); if (err != KErrNone) { // Handle error. Initialization has failed, // client cannot generate HSLP address from IMSI. User::Leave(err); } } // Active object RunError TInt CMySettingsClientClass::RunError(TInt aError) { // Leave has happened in RunL and ignored return KErrNone; } // Method to initialize SUPL Settings void CMySettingsClientClass::InitializeSettings() { iSettings->Initialize(iStatus); SetActive(); } // Method to generate the HSLP Address from IMSI obtained during // initialization. The HSLP Address generation functionality is provided // by SUPL Settings API void CMySettingsClientClass::GenerateHSLPAddress() { TInt err = iSettings->GenerateHslpAddressFromImsi(iNewHslpAddr); if (err != KErrNone) { // Handle error } }
![]() |
SUPL Settings API can be used to check whether the IMSI currently stored in SUPL Settings is different from IMSI obtained during initialization. The following diagram illustrates the steps involved in checking whether IMSI has changed or not using SUPL Settings API.
The following code snippets illustrates how to check whether IMSI has changed or not using SUPL Settings API.
#include <epos_csuplsettings.h> #include <epos_csuplsettingsconstants.h> class CMySettingsClientClass : public CActive { public: // Two phase construction static CMySettingsClientClass* NewL(); // Destructor ~CMySettingsClientClass(); // InitializeSettings Method void InitializeSettings(); protected : // From CActive // Overriding RunL void RunL(); // Overriding RunError TInt RunError(TInt aError); // Overriding DoCancel void DoCancel(); public: // Helper methods // Method to determine if the IMSI value in the // SUPL Settings is different from the // IMSI obtained during initialization TBool HasImsiChanged(); private: // Data // SUPL Settings CSuplSettings* iSettings; }; // Two phase construction void CMySettingsClientClass::ConstructL() { iSettings = CSuplSettings::NewL(); } // Static method for object instantiation void CMySettingsClientClass::NewL() { CMySettingsClientClass * self = new (ELeave) CMySettingsClientClass; CleanupStack::PushL(self); self->ConstructL(); CleanupStack::Pop(self); return self; } // Destructor CMySettingsClientClass::~CMySettingsClientClass() { delete iSettings; } // Cancellation method for the active object void CMySettingsClientClass::DoCancel() { // This method gets invoked only when // the object is active iSettings->CancelInitialize(); } // Active object RunL void CMySettingsClientClass::RunL() { TInt err = iStatus.Int(); if (err != KErrNone) { // Handle error. Initialization has failed, // client cannot check whether the currently // active IMSI is different from the IMSI currently // present in the SUPL settings. User::Leave(err); } } // Active object RunError TInt CMySettingsClientClass::RunError(TInt aError) { // Leave has happened in RunL and ignored return KErrNone; } // Method to initialize SUPL Settings void CMySettingsClientClass::InitializeSettings() { iSettings->Initialize(iStatus); SetActive(); } // Method that determines if the IMSI in SUPL Settings is // same as or different from IMSI obtained during initialization TBool CMySettingsClientClass::HasImsiChanged() { TBool changed; TInt err = iSettings->IsImsiChanged(changed); if (err != KErrNone) { // Handle error } return changed; }
![]() |
KErrNotReady | This error code is returned in the following cases:
In all the above cases, client should initialize the settings object first and perform the required operation. |
KErrGeneral | This error code is returned in the following cases
|
KErrPermissionDenied | If client does not have WriteDeviceData capability when changing SUPL Settings or if the client does not have the ReadDeviceData capability when initializing the SUPL Settings object. |
KErrArgument | If any of the arguments passed to the SUPL Settings methods are not valid. Client should pass the valid arguments for SUPL Settings methods. |
KErrOverflow | If the descriptor passed as argument is too small to retrieve the value from SUPL Settings Storage. Client should have allocated enough memory to hold the value retrieved from SUPL Settings. |
KErrAlreadyExists | If observer has already been set. |
![]() |
![]() |
API | Application Programming Interface |
FQDN | Fully Qualified Domain Name |
HSLP | Home SUPL Location Platform |
IAP | Internet Accept Point |
IMSI | International Mobile Subscriber Identity |
MCC | Mobile Country Code |
MNC | Mobile Network Code |
OMA | Open Mobile Alliance |
SET | SUPL Enabled Terminal |
SLP | SUPL Location Platform |
SUPL | Secure User Plane Location Protocol |
![]() |
Framework |
Usually denotes the collection of an engine and associated programming interfaces. This document mentions SUPL Framework. |
SUPL Enabled Terminal | A device that is capable of communicating with a SUPL network. Examples of this could be UE in UMTS, MS in GSM or IS95. |
SUPL Location Platform (SLP) | Network entity responsible for Service management and Position determination. |
![]() |
1. OMA-AD-SUPL-V1_0 |
SUPL Architecture Description by OMAhttp://member.openmobilealliance.org/ |
2. OMA-TS-ULP-V1 | SUPL Technical Specification by OMA http://member.openmobilealliance.org/ |
3. OMA-TS-ULP-V2 | SUPL Technical Specification by OMA http://member.openmobilealliance.org/ |
![]() |