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

The SUPL Settings API is a Domain API.

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.


Related APIs
  • CSuplSettings
  • MSuplSessionObserver
  • MSuplSettingsObserver

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.

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.


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.


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.


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.


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.


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.


Following diagram shows how client can get parameters of a given session by providing a valid session id.


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.


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.


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.


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.


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
        }
    }
Related APIs
  • CSuplSettings
  • HandleSuplSessionChangeL()
  • HandleSuplSettingsChangeL()
  • MSuplSessionObserver
  • MSuplSettingsObserver
  • RemoveObserver()
  • RemoveSessionObserver()
  • SetObserverL()
  • SetSessionObserverL()

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.


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.


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.


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.


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 the Symbian platform. 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.

Related APIs
  • KErrAlreadyExists
  • KErrArgument
  • KErrGeneral
  • KErrNotReady
  • KErrOverflow
  • KErrPermissionDenied
  • ReadDeviceData
  • WriteDeviceData

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.

Related APIs
  • AddNewServer()
  • CancelTriggerSession()
  • ChangePriority()
  • GenerateHslpAddressFromImsi()
  • GetImsi()
  • Initialize()
  • IsImsiChanged()
  • ReadDeviceData
  • RemoveServer()
  • SetAllParameter()
  • SetAsDefault()
  • SetDefaultServer()
  • SetFallBack()
  • SetIapName()
  • SetNotificationStatus()
  • SetServerAddress()
  • SetServerEnabledFlag()
  • SetSuplUsage()
  • SetUsageInHomwNwFlag()
  • WriteDeviceData

Glossary

Abbreviations

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

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 OMA http://member.openmobilealliance.org/

2. OMA-TS-ULP-V1

SUPL Technical Specification by OMA http://member.openmobilealliance.org">http://member.openmobilealliance.org/

3. OMA-TS-ULP-V2

SUPL Technical Specification by OMA http://member.openmobilealliance.org/