S60 5.2 SUPL Settings API

DN0756875
CONFIDENTIAL

©Nokia Corporation and/or its subsidiaries 2009
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.0

29.06.2009

Approved

 


Table of Contents

Changes
Purpose
Constraints
Classification and release information
Emulator support
API description
Use cases
API class structure
Using SUPL Settings API
Set/Get SUPL settings
Add new server properties to SUPL settings
Change properties of existing server
Set SUPL Usage in SUPL Settings
Change fallback in SUPL Settings
Get server properties from SUPL Settings
Get SUPL Usage from SUPL Settings
Get active trigger session parameters
Modify active SUPL trigger session parameters
Cancelling Sessions
Listening to SUPL Settings changes
Change Priority
Change priority of servers in SUPL settings
Using IMSI obtained during initialization
Get IMSI
Generate HSLP address from IMSI
Check if IMSI has changed or not
Error handling
Memory overhead
Extensions to the API
Limitations of the API
Glossary
Abbreviations
Definitions
References

 


Changes

The following header file(s) have been added in S60 5.2:
  • epos_msuplsessionobserver.h
The following header file(s) have been modified in S60 5.2:
  • epos_csuplsettings.h
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 )
  • epos_csuplsettingparams.h
Type Class Change
New public method CTriggerParams TInt Set()
New public method CTriggerParams TInt Get()
  • epos_csuplsettingconstants.h
Type Class Change
New constant const TInt KMaxTriggerSessionNameLen=256;

 


Purpose

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.

 


Constraints

None.

 


Classification and release information

The SUPL Settings API is a Domain API and part of S60 release 3.1 and onwards. This document is valid for S60 5.2 and onwards.

 


Emulator support

This API is supported in the WINS/WINSCW emulator environment, with the following exceptions:
  • IMSI related methods will not work properly

 


API description

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.

SUPL settings also maintains active SUPL trigger session information. Session information contains:
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.

 


Use cases

The use cases of SUPL Settings API are:

Get/Set SUPL settings

  • Add new server properties to SUPL settings
  • Get server properties from SUPL settings
  • Change properties of existing server
  • Get SUPL Usage
  • Set SUPL Usage
  • Change Fallback
  • Get active SUPL trigger session parameters
  • Modify active SUPL trigger session parameters
  • Cancelling sessions

Change Priority

  • Change priority of servers in SUPL settings to either increase or decrease priority.

Listening to SUPL Settings changes

  • Start listening to SUPL settings changes so that events are received when there are any changes in the SUPL settings

Using IMSI obtained during initialization

  • Get IMSI
  • Generate HSLP address from IMSI
  • Check if IMSI has changed or not

 


API class structure

The three main classes of SUPL Settings API are CSuplSettings, MSuplSettingsObserver and MSuplSessionObserver. CSuplSettings is used for accessing SUPL Settings. MSuplSettingsObserver is an interface class. This class must be implemented by the client who wants to receive notifications when any change occurs in SUPL Settings. MSuplSessionObserver is also an interface class. This class must be implemented by the client who wants to receive notifications when any change occurs in SUPL Active Sessions Settings database. The following diagram presents the class hierarchy and methods.
Figure 1: SUPL Settings classes

 


Using SUPL Settings API

The capability requirements for the client application using SUPL Settings API are as follows:
  • Following methods require the ReadDeviceData capability:
    • Initialize()
    • GenerateHslpAddressFromImsi()
    • GetImsi()
    • IsImsiChanged()
    • GetTriggerParams( RPointerArray(<CTriggerParams>& )
    • GetTriggerParams( TInt,CTriggerParams*& )
  • Following method require the WriteDeviceData capability:
    • SetSuplUsage()
    • AddNewServer()
    • SetServerAddress()
    • SetIapName()
    • SetSuplUsage()
    • SetServerEnabledFlag()
    • SetUsageInHomwNwFlag()
    • SetAllParameter()
    • SetDefaultServer()
    • SetAsDefault()
    • RemoveServer()
    • ChangePriority()
    • SetFallBack()
    • SetNotificationStatus()
    • CancelTriggerSession()
  • All other methods do not require any capability.

 


Set/Get SUPL settings

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.

 


Add new server properties to SUPL settings

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.

Figure 2: Add new server properties to SUPL settings

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;
  }

 


Change properties of existing server

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.

Figure 3: Change properties of existing server

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;
  }

 


Set SUPL Usage in SUPL Settings

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.

Figure 4: Set SUPL usage in SUPL settings

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
            }
     }

 


Change fallback in SUPL Settings

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.

Figure 5: Set fallback in SUPL settings

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 
            }
        }            
    }

 


Get server properties from SUPL Settings

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.

Figure 6: Get server properties from SUPL Settings

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;
  }

 


Get SUPL Usage from SUPL Settings

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.

Figure 7: Get SUPL Usage from SUPL Settings

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
        }
    }

 


Get active trigger session parameters

A client may retrieve parameters of all active trigger sessions or parameters of a given session from SUPL Settings.

The following diagram illustrates the steps involved in retrieving parameters of all active trigger sessions.
Figure 8: Get all trigger sessions

Following diagram shows how client can get parameters of a given session by providing a valid session id.
Figure 9: Get a given trigger session

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;
    } 

 


Modify active SUPL trigger session parameters

Client can set/reset "Notification Status" attribute for a given session.

The following diagram illustrates the steps involved in modifying notification status attribute using SUPL Settings API.
Figure 10: Set Notification Status

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
			  }
		 }

 


Cancelling Sessions

Client can cancel/stop ongoing SUPL triggered session using SUPL Settings API. Cancelling ongoing session results in removal of given session information from settings database and cancelling the corresponding session in SUPL server. The following diagram illustrates the steps involved in cancelling active SUPL triggered session.
Figure 11: Cancel a given trigger session

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
			  }
		}

 


Listening to SUPL Settings changes

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.

The following diagram illustrates the steps involved in listening to the SUPL Settings changes, receiving change events and read new values from settings and stop listening SUPL Settings changes using SUPL Settings API.
Figure 12: 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 diagram illustrates the steps involved in listening to SUPL session parameter changes using SUPL Settings API.
Figure 13: Listening to SUPL trigger session 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
        }
    }

 


Change Priority

The order of server entries in SUPL settings is priority of servers.

 


Change priority of servers in SUPL settings

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.

Figure 14: Change Priority

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;
    }

 


Using IMSI obtained during initialization

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.

 


Get IMSI

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.

Figure 15: Get IMSI

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 
        }  
    }

 


Generate HSLP address from IMSI

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.

Figure 16: Generate HSLP address from IMSI

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 
        }  
    }

 


Check if IMSI has changed or not

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.

Figure 17: Check if IMSI has changed or not

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;
    }

 


Error handling

The interface uses the system-wide error codes of Symbian OS. The error codes returned by SUPL Settings API are:
KErrNotReady This error code is returned in the following cases:
  • If the settings object is not initialized before calling the method to check whether IMSI has changed or not.
  • If the settings object is not initialized before calling the method to get IMSI.

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
  • If the changing of SUPL settings has failed.
  • If Initialization fails. Client can initialize settings object after some time.
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.

 


Memory overhead

SUPL Settings object is created by clients and it adds an additional memory to client. Settings API internally uses object to interact with CenRep and ETel. As a guideline, the client shall delete the settings object to release memory held after the processing is complete.

 


Extensions to the API

None.

 


Limitations of the API

None.

 


Glossary

 


Abbreviations

Table:
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

 


Definitions

Table:

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.

 


References

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/

Back to top