1 /*

     2 * Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  SUPL Settings class

    15 *

    16 */

    17 

    18 

    19 #ifndef __EPOS_CSUPLSETTINGS_H__

    20 #define __EPOS_CSUPLSETTINGS_H__

    21 

    22 //  INCLUDES

    23 #include <e32base.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class CSuplSettingsEngine;

    27 class MSuplSettingsObserver;

    28 class MSuplSessionObserver;

    29 class CSuplSettingsNotifier;

    30 class CSuplSessionNotifier;

    31 class CServerParams;

    32 class CTriggerParams;

    33 

    34 // CONSTANTS

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39 *  This class is used for accessing SUPL settings. The SUPL settings 

    40 *  contains information such about server properties which includes following:

    41 *

    42 *  Server address in string format.  This is an HSLP address used for SUPL connection.

    43 *  Protocol version in mmnn format where mm indicates minor version nn is major version

    44 *  The Internet Access Point Name refers to the access point which is used to access the HSLP over the internet.  

    45 *  This can have maximum size of 100 characters.

    46 *  Manufacturer name of server indicates the server manufacturer.

    47 *  Time stamp when last used. 

    48 *  Time stamp when last tried. 

    49 *  Network info when the server was last used 

    50 *  Network info when the server was last used sucessfully

    51 *  Information on whether server supports emergency support or not

    52 *  Information on whether server supports TLS or not

    53 *  Information on whether server supports PSK-TLS or not

    54 *  Information on whether server enabled or not

    55 *  Information on whether this server entry needs to be deleted when SIM changes 

    56 *  Information on whether server can be used in the home network or not 

    57 *  Information on whether this server entry can be edited or not 

    58 *  SUPL Usage indicates whether user should be notified before using SUPL.

    59 *  Fallback indicates whether fallback is allowed or not if SUPL session fails with default server.

    60 *

    61 *  From the abover properties, only following fieds can be changed by SUPL settings client:

    62 *  - SLP address

    63 *  - IAP / destination.

    64 *  - SLP enabled / disabled.

    65 *  - Remove SLP, when SIM change ( yes / no ).

    66 *  - Usage in home network ( yes / no ).

    67 *  - Editable ( yes / no).

    68 *

    69 *  This is part of @lib epos_suplsettings.lib

    70 *  @since S60 5.1 

    71 */

    72 

    73 class CSuplSettings : public CBase

    74     {

    75     public:  

    76                   

    77         /**

    78          * Enumeration to indicate SUPL usage.  This is used as parameter for 

    79          * @ref SetSuplUsage() method. Client has to select one of the values from

    80 	     * this enumeration when changing SUPL usage.  For example, if client is 

    81          * changing SUPL usage to "always ask", it should select ESuplUsageAlwaysAsk. 

    82          * If SUPL usage is set to ESuplUsageDisabled,

    83          * SUPL cannot be used. 

    84          *

    85          * Client can get SUPL usage using @ref GetSuplUsage() method.

    86          *

    87          * @since S60 3.2

    88          */

    89         enum TSuplSettingsUsage

    90             {

    91             /** Indicates that user should be asked always before SUPL usage */ 

    92             ESuplUsageAlwaysAsk = 0, 

    93             /** Indicates that SUPL can be used without asking user */ 

    94             ESuplUsageAutomatic, 

    95             /** Indicates that SUPL can be used without asking user in the home network and 

    96             * user should be notified in the visiting network */ 

    97             ESuplUsageHomeAutomatic, 

    98             /** Indicates that SUPL usage is disabled */ 

    99             ESuplUsageDisabled 

   100             };                

   101 

   102 

   103     public:  // Constructors and destructor

   104 

   105         /**

   106         * Two-phased constructor.

   107         *

   108         * @since S60 3.1

   109         * @returns A new instance of this class.

   110         */

   111         IMPORT_C static CSuplSettings* NewL();

   112 

   113         /**

   114         * Two-phased constructor.

   115         *

   116         * @since S60 5.1 

   117         * @returns A new instance of this class.

   118         */

   119         IMPORT_C static CSuplSettings* NewLC();

   120 

   121         /**

   122         * Destructor.

   123         *

   124         * @since S60 3.1

   125         *

   126         */

   127         IMPORT_C ~CSuplSettings();

   128 

   129     protected:

   130 

   131         /**

   132         * C++ default constructor.

   133         *

   134         * @since S60 3.1

   135         *

   136         */

   137         CSuplSettings();

   138 

   139         /**

   140         * By default EPOC constructor is private.

   141         *

   142         * @since S60 3.1

   143         *

   144         */

   145         void ConstructL();

   146 

   147     public: // New functions

   148 

   149         /**

   150         * This method is used to start listening for SUPL setting changes. To

   151         * listen for changes, the client must implement the

   152         * @ref MSuplSettingsObserver interface.  Client must allocated memory 

   153         * for the observer.

   154         *

   155         * Listening can be stopped by invoking @ref RemoveObserver().

   156         *

   157         * @since S60 3.1

   158         *

   159         *

   160         * @param [IN] aObserver The observing object.

   161 	    * @return one of the following values

   162 	    * 	- KErrNone if setting observer is successful

   163 	    * 	- KErrAlreadyExists if observer is already set 

   164 	    *  

   165         */

   166         IMPORT_C TInt SetObserverL(

   167                MSuplSettingsObserver& aObserver

   168         );

   169 

   170         /**

   171          * This method is used to stop listening for SUPL setting changes.  After removing observer,

   172          * client has to free the memory allocated for the observer.  If this method is invoked without

   173          * setting observer using @ref SetObserverL() method, the request is silently ignored.

   174          *

   175          * @since S60 3.1

   176          *

   177          */

   178         IMPORT_C void RemoveObserver();

   179 

   180         /**

   181         * This method is used to start listening for SUPL session changes. To

   182         * listen for changes, the client must implement the

   183         * @ref MSuplSessionObserver interface.  Client must allocated memory 

   184         * for the observer.

   185         *

   186         * Listening can be stopped by invoking @ref RemoveSessionObserver().

   187         *

   188         * @since 

   189         *

   190         *

   191         * @param [IN] aObserver The observing object.

   192 	    * @return one of the following values

   193 	    * 	- KErrNone if setting observer is successful

   194 	    * 	- KErrAlreadyExists if observer is already set 

   195 	    *  

   196         */

   197         IMPORT_C TInt SetSessionObserverL(

   198                MSuplSessionObserver& aObserver

   199         );

   200 

   201         /**

   202          * This method is used to stop listening for SUPL session changes.  After removing observer,

   203          * client has to free the memory allocated for the observer.  If this method is invoked without

   204          * setting observer using @ref SetSessionObserverL() method, the request is silently ignored.

   205          *

   206          * @since 

   207          *

   208          */

   209         IMPORT_C void RemoveSessionObserver(); 

   210         

   211         

   212         /**

   213          * This method is invoked to initialize SUPL settings object.  This is 

   214          * an asynchronous call and client can cancel this request by invoking 

   215          * @ref CancelInitialize().  

   216          * During initialization, current IMSI value is obtained from

   217 	     * the system. Client should invoke this method to re-read the IMSI if the client detects 

   218          * an IMSI change.

   219          *

   220          * Note that if @ref Initialize() method is invoked after started listening to 

   221          * SUPL settings changes by invoking @ref SetObserverL(), listening is not stopped.

   222          *

   223          * @since S60 3.1

   224          *

   225 	     * @param [OUT] aStatus To return result code.  It will hold one of the following values

   226          * after completion:

   227 	     * 	- KErrNone if intialization is successful

   228          * 	- KErrGeneral if initialization has failed (initialization can fail if SIM card is not present)

   229          * 	- KErrCancel if initialization is cancelled

   230          *

   231          */ 

   232 

   233         IMPORT_C void Initialize(TRequestStatus& aStatus);

   234     

   235         /**

   236          * This method is invoked to cancel @ref CSuplSettings::Initialize().

   237          *

   238          * @since S60 3.1

   239          *

   240          */

   241         

   242         IMPORT_C void CancelInitialize();

   243 

   244         

   245 

   246 	/**

   247 	 * This method can be used to generate HSLP address from the IMSI

   248      * obtained during initialization.  

   249      * HSLP address in the FQDN format can have maximum size of

   250      * 256 bytes.  Client must allocate enough memory to hold the HSLP address.

   251      * HSLP address can be generated from IMSI, for example,

   252      * if HSLP address read from SUPL settings is empty or not valid.  

   253      * The generated HSLP is in the FQDN format and looks like 

   254      * "h-slp.mncXXX.mccYYY.3gppnetwork.org" 

   255      * where XXX and YYY values for MNC and MCC extracted from the IMSI.

   256      *

   257      * This method should be invoked only after 

   258      * @ref Initialize() is completed with KErrNone.  

   259 	 *

   260      * @since S60 3.1

   261      *

   262 	 * @param [OUT] aHslpAddress will hold, on successful completion, HSLP address generated 

   263      * from IMSI obtained during initialization.  HSLP address can be of size 256 bytes.

   264 	 * @return one of the following error codes

   265 	 *	- KErrNone if method completed successfully

   266      *	- KErrOverflow if the descriptor is too small to hold the HSLP address 

   267 	 *	- KErrNotReady if this method is invoked before @ref Initialize or @ref Initialize has not completed with @p KErrNone

   268      *	- KErrArgument if argument passed is of length zero

   269 	 */

   270 

   271 	IMPORT_C TInt GenerateHslpAddressFromImsi(TDes& aHslpAddress);

   272     

   273     /**

   274      * This method returns IMSI obtained during initialization of SUPL settings object.  

   275      * This method should be invoked after @ref Initialize() is completed with KErrNone.  

   276      *

   277      * @since S60 3.1

   278      *

   279      * @param [OUT] aImsi will hold, on successful completion, IMSI obtained during initialization.  

   280      * IMSI can have maximum size of 15 characters.

   281      * If SUPL Settings library is unable to retrieve the IMSI value during initialization, 

   282      * aImsi will be a descriptor of length zero.

   283      * @return one of the following error codes returned

   284      *  - KErrNone if method completed successfully

   285      *  - KErrNotReady if this method is invoked before @ref Initialize or @ref Initialize has not 

   286      *  completed with @p KErrNone

   287      *  - KErrArgument if argument passed is of length zero 

   288      *  - KErrOverflow if the descriptor is too small to hold the IMSI 

   289      *

   290      */

   291 

   292     IMPORT_C TInt GetImsi(TDes& aImsi);

   293 

   294     /**

   295      * This method compares IMSI value currently stored in SUPL settings storage with

   296      * IMSI value obtained during initialization. If IMSI value obtained during 

   297      * initialization and IMSI value stored in SUPL settings storage are same, this method returns false 

   298      * otherwise true is returned.   

   299      * This method should be invoked after @ref Initialize() is completed with KErrNone.  

   300      * 

   301      * @since S60 3.1

   302      *

   303      * @param [OUT] aChanged will hold, on successful completion, one of the following value

   304      *   - ETrue if IMSI obtained during initialization and IMSI value stored in SUPL settings

   305      *   are different.

   306      *   - EFalse if IMSI obtained during initialization and IMSI value stored in SUPL settings

   307      *   are same.

   308      * @return one of the following

   309      *  - KErrNone if method completed successfully

   310      *  - KErrNotReady if this method is invoked before @ref Initialize or @ref Initialize has not completed with @p KErrNone 

   311      */

   312     

   313     IMPORT_C TInt IsImsiChanged(TBool& aChanged);

   314     

   315     /**

   316      * This method is used to retrieve SUPL usage from settings storage.  

   317      *

   318      * @since S60 3.2

   319      *

   320      * @param [OUT] aUsage  will hold, upon successful completion, value indicating 

   321      * current SUPL usage 

   322      * @return one of the following error codes: 

   323      *         - KErrNone if SUPL usage retrieved successfully.  

   324      *         - KErrNotFound if the SUPL State is not found in SUPL settings

   325      *         - KErrUnknown if retrieving SUPL usage from settings storage failed

   326      */

   327 

   328     IMPORT_C TInt GetSuplUsage(TSuplSettingsUsage& aUsage) const;

   329 

   330     /**

   331      * This method is used to change SUPL usage.  Using this method, SUPL usage can be 

   332      * set to any of the values specified in the enumeration @ref TSuplSettingsUsage 

   333      * By default, SUPL usage will be set to always ask. 

   334      *

   335      * @since S60 3.2

   336      *

   337      * @param [IN] aUsage Usage to be set for SUPL usage 

   338      * @return one of the following error codes: 

   339      *         - KErrNone if SUPL usage is changed successfully.  

   340      *         - KErrArgument if aUsage field is not in range

   341      *         - KErrUnknown if changing SUPL usage in settings storage has failed

   342      */

   343     IMPORT_C TInt SetSuplUsage(TSuplSettingsUsage aUsage);

   344 

   345     /**

   346      * This method is used to add new server into settings.  It is client's responsibility

   347      * to set all the parameters in aParamValues except SLP identification.  After adding

   348      * server entry, the server identity generated will be retuned with aSlpId.  The returned

   349      * server identity can be used with other methods change any of server parameters. If server 

   350      * entry with the same server address already presnt, then this method returns error.

   351      *

   352      * @since S60 5.1 

   353      *

   354      * @param [IN] aParamValues Server parameter values which which the server entry needs to be added 

   355      * @param [OUT] aSlpId SLP identification for the new server added 

   356      * @return one of the following error codes: 

   357      *         - KErrNone if SUPL settings are changed successfully.  

   358      *         - KErrAlreadyExists if the server address mentioned in aParamValues already present in settings 

   359      *         - KErrGeneral if changing SUPL settings has failed 

   360      */ 

   361     IMPORT_C TInt AddNewServer( 

   362             const CServerParams *aParamValues, 

   363             TInt64& aSlpId 

   364     );

   365 

   366 

   367     /**

   368      * This method is used to change server address parameter in server settings 

   369      *

   370      * @since S60 5.1 

   371      *

   372      * @param [IN] aSlpId SLP ID for which the parameter needs to be changed 

   373      * @param [IN] aServerAddres SUPL Server address 

   374      * @return one of the following error codes: 

   375      *         - KErrNone if SUPL settings are changed successfully.  

   376      *         - KErrArgument if address passed is empty or if the SLP ID passed is not valid 

   377      *         - KErrGeneral if changing SUPL settings has failed 

   378      */

   379 

   380     IMPORT_C TInt SetServerAddress( 

   381             const TInt64 aSlpId, 

   382             const TDesC& aServerAddress

   383     );

   384 

   385     /**

   386      * This method is used to retrieve server address parameter from server settings.  Client

   387      * has to allocate memory for server address parameter.

   388      *

   389      * @since S60 5.1 

   390      *

   391      * @param [IN] aSlpId SLP ID of server for which the server address needs to be retrieved 

   392      * @param [OUT] aServerAddres SUPL Server address 

   393      * @return one of the following error codes: 

   394      *         - KErrNone if server address is retrieved successfully 

   395      *         - KErrArgument if the SLP ID passed is not valid 

   396      */

   397 

   398     IMPORT_C TInt GetServerAddress( 

   399             TInt64 aSlpId, 

   400             TDes& aServerAddress

   401     ) const;

   402 

   403     /**

   404      * This method is used to change IAP Name in server parameters. IAP name refers to 

   405      * the access point which is used to access the HSLP over the internet. 

   406      *

   407      * @since S60 5.1 

   408      *

   409      * @param [IN] aSlpId SLP ID for which the parameter needs to be changed 

   410      * @param [IN] aIapName The Internet Access Point Name refers to the access point which is 

   411      * used to access the HSLP over the internet.  This can have maximum size of 100 characters. 

   412      * @return one of the following error codes: 

   413      *         - KErrNone if SUPL settings are changed successfully.  

   414      *         - KErrArgument if IAP Name is empty or if the SLP ID passed is not valid 

   415      *         - KErrGeneral if changing SUPL settings has failed 

   416      */

   417     IMPORT_C TInt SetIapName( 

   418             const TInt64 aSlpId, 

   419             const TDesC& aIapName

   420     );

   421 

   422     /**

   423      * This method is used to retrieve IAP Name in server parameters. IAP name refers to 

   424      * the access point which is used to access the HSLP over the internet. It is client's

   425      * responsibility to allocate memory for IAP name before invoking this method.

   426      *

   427      * @since S60 5.1 

   428      *

   429      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   430      * @param [OUT] aIapName The Internet Access Point Name refers to the access point which is 

   431      * used to access the HSLP over the internet.  This can have maximum size of 100 characters. 

   432      * @return one of the following error codes: 

   433      *         - KErrNone if IAP name is retrieved successfully 

   434      *	      - KErrOverflow if the descriptor is too small to hold the IAP name 

   435      *         - KErrArgument if the SLP ID passed is not valid 

   436      */

   437     IMPORT_C TInt GetIapName( 

   438             const TInt64 aSlpId, 

   439             TDes& aIapName

   440     ) const;

   441 

   442 

   443     /**

   444      * This method is used to change parameter which indicates whether server

   445      * can be used for SUPL session or not. 

   446      *

   447      * @since S60 5.1 

   448      *

   449      * @param [IN] aSlpId SLP ID for which the parameter needs to be changed 

   450      * @param [IN] aEnable Flag to indicate whether server can be enabled or not 

   451      * @return one of the following error codes: 

   452      *         - KErrNone if SUPL settings are changed successfully.  

   453      *         - KErrArgument if the SLP ID passed is not valid 

   454      *         - KErrGeneral if changing SUPL settings has failed 

   455      */

   456     IMPORT_C TInt SetServerEnabledFlag(

   457             const TInt64 aSlpId, 

   458             const TBool aEnable 

   459     );

   460 

   461     /**

   462      * This method is used to retrieve parameter which indicates whether server

   463      * can be used for SUPL session or not. 

   464      *

   465      * @since S60 5.1 

   466      *

   467      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   468      * @param [OUT] aEnable Flag to indicate whether server can be enabled or not 

   469      * @return one of the following error codes: 

   470      *         - KErrNone if server available flag is retrieved successfully 

   471      *         - KErrArgument if the SLP ID passed is not valid 

   472      */

   473     IMPORT_C TInt GetServerEnabledFlag(

   474             const TInt64 aSlpId, 

   475             TBool& aEnable 

   476     ) const;

   477 

   478     /**

   479      * This method is used to change parameter which indicates whether server

   480      * details can be removed if SIM is changed. 

   481      *

   482      * @since S60 5.1 

   483      *

   484      * @param [IN] aSlpId SLP ID for which the parameter needs to be changed 

   485      * @param [IN] aSimChangeFlag Flag to indicate whether server can be removed or not if there is a SIM change 

   486      * @return one of the following error codes: 

   487      *         - KErrNone if SUPL settings are changed successfully.  

   488      *         - KErrArgument if the SLP ID passed is not valid 

   489      *         - KErrGeneral if changing SUPL settings has failed 

   490      */

   491     IMPORT_C TInt SetSimChangeRemoveFlag(

   492             const TInt64 aSlpId, 

   493             const TBool aSimChangeFlag 

   494     );

   495 

   496     /**

   497      * This method is used to retrieve parameter which indicates whether server

   498      * details can be removed if SIM is changed. 

   499      *

   500      * @since S60 5.1 

   501      *

   502      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   503      * @param [OUT] aSimChangeFlag Flag to indicate whether server can be removed or not if there is a SIM change 

   504      * @return one of the following error codes: 

   505      *         - KErrNone if SIM change removal flag is retrieved successfully 

   506      *         - KErrArgument if the SLP ID passed is not valid 

   507      */

   508     IMPORT_C TInt GetSimChangeRemoveFlag(

   509             const TInt64 aSlpId, 

   510             TBool& aSimChangeFlag 

   511     ) const;

   512 

   513     /**

   514      * This method is used to change parameter which indicates whether server

   515      * can be used out side home network or not. 

   516      *

   517      * @since S60 5.1 

   518      *

   519      * @param [IN] aSlpId SLP ID for which the parameter needs to be changed 

   520      * @param [IN] aHomeNwFlag Flag to indicate whether server can be used outside home network or not 

   521      * @return one of the following error codes: 

   522      *         - KErrNone if SUPL settings are changed successfully.  

   523      *         - KErrArgument if the SLP ID passed is not valid 

   524      *         - KErrGeneral if changing SUPL settings has failed 

   525      */

   526     IMPORT_C TInt SetUsageInHomwNwFlag(

   527             const TInt64 aSlpId, 

   528             const TBool aHomeNwFlag 

   529     );

   530 

   531     /**

   532      * This method is used to retrieve parameter which indicates whether server

   533      * can be used out side home network or not. 

   534      *

   535      * @since S60 5.1 

   536      *

   537      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   538      * @param [OUT] aHomeNwFlag Flag to indicate whether server can be used outside home network or not 

   539      * @return one of the following error codes: 

   540      *         - KErrNone if home network usage flag is retrieved successfully 

   541      *         - KErrArgument if the SLP ID passed is not valid 

   542      */

   543     IMPORT_C TInt GetUsageInHomwNwFlag(

   544             const TInt64 aSlpId, 

   545             TBool& aHomeNwFlag 

   546     ) const;

   547 

   548 

   549     /**

   550      * This method is used to change parameter which indicates whether server

   551      * details are editable or not. 

   552      *

   553      * @since S60 5.1 

   554      *

   555      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   556      * @param [IN] aEditFlag Flag to indicate whether server details are editable or not 

   557      * @return one of the following error codes: 

   558      *         - KErrNone if editable flag is retrieved successfully 

   559      *         - KErrArgument if the SLP ID passed is not valid 

   560      *         - KErrGeneral if SUPL settings cannot be changed

   561      */ 

   562     IMPORT_C TInt SetEditableFlag( 

   563             const TInt64 aSlpId, 

   564             const TBool aEditFlag 

   565     ) const;

   566 

   567        /**

   568      * This method is used to retrieve parameter which indicates whether server

   569      * details are editable or not. 

   570      *

   571      * @since S60 5.1 

   572      *

   573      * @param [IN] aSlpId SLP ID for which the parameter needs to be retrieved 

   574      * @param [OUT] aEditFlag Flag to indicate whether server details are editable or not 

   575      * @return one of the following error codes: 

   576      *         - KErrNone if editable flag is retrieved successfully 

   577      *         - KErrArgument if the SLP ID passed is not valid 

   578      */ 

   579     IMPORT_C TInt GetEditableFlag( 

   580             const TInt64 aSlpId, 

   581             TBool& aEditFlag 

   582     ) const;

   583 

   584     /**

   585      * This method is used to change all parameters of server in SUPL settings.  The server identity

   586      * in @ref CServerParams which is passed as parameter gives information on for which server

   587      * entry the values needs to be changed.  If the passed server identity does not exists in

   588      * settings, error is returned.  

   589      *

   590      * @since S60 5.1 

   591      *

   592      * @param [IN] aParamValues New value for server parameters. 

   593      * @ref CServerParams class

   594      * @return one of the following error codes: 

   595      *         - KErrNone if SUPL settings are changed successfully.  

   596      *         - KErrArgument if the value of any of the pamater is not in range

   597      *         - KErrNotFound if the SLP Identity mentioned in aParamValues does not exist in settings 

   598      *         - KErrGeneral if changing SUPL settings has failed 

   599      */

   600 

   601     IMPORT_C TInt SetAllParameter( 

   602             const CServerParams *aParamValues

   603     );

   604 

   605     /**

   606      * This method is used to change all parameters of default server in SUPL settings.  In this

   607      * method server identity of @ref CServerParams passed is not considered and values

   608      * of default server is updated except server identity.  If none of the server is set

   609      * as default, the new server entry will be added and will be marked as default.  Client can

   610      * use @ref GetDefaultSlpId() method to get SLP identity of default server entry.

   611      *

   612      * @since S60 5.1 

   613      *

   614      * @param [IN] aParamValues Parameter for which the value needs to be changed  

   615      * @ref CServerParams class

   616      * @return one of the following error codes: 

   617      *         - KErrNone if SUPL settings are changed successfully.  

   618      *         - KErrArgument if the value of any of the pamater is not in range

   619      *         - KErrGeneral if changing SUPL settings has failed 

   620      */

   621 

   622     IMPORT_C TInt SetDefaultServer( 

   623             const CServerParams *aParamValues

   624     );

   625 

   626 

   627     /**

   628      * This method is deletes server entry from SUPL settings storage.  

   629      *

   630      * @since S60 5.1 

   631      *

   632      * @param [IN] aSlpId Server identity for which the entery needs to be deleted from the SUPL settings storage 

   633      *

   634      * @return one of the following error codes: 

   635      *         - KErrNone if entry is deleted sucessfully 

   636      *         - KErrNotFound if the specified server identity does not exists in settings storage 

   637      *         - KErrGeneral if changing SUPL settings has failed 

   638      *

   639      */

   640     IMPORT_C TInt RemoveServer(const TInt64 aSlpId);

   641 

   642        /**

   643         * This method changes the priority of the server to the specified priority.  Here the priority 

   644         * refers to the order of server entries in the SUPL settings storage.  If the priority of server

   645         * is changed from position N to M and N > M, then the priority of all the server entries from Mth

   646         * position will get. If the priority of server is changed from position N to M and

   647         * N < M, then the priority of all servers from N+1 whill get changed. Priority is not valid if the

   648         * mentioned priority specified beyond the number of number of servers already present in the settings.

   649         * For example, if the specified priority is N and number of server entries in the settings in M,

   650         * then N is invalid if N > M.

   651         *

   652         * The parameter aDirection specifies whether the server to be moved up or down.  If this has value

   653         * ETrue server will be moved up.  Else server will be moved down.

   654         *

   655         * @since S60 5.1 

   656         *

   657         * @param [IN] aSlpId Server identity for which the priority needs to be changed 

   658         * @param [IN] aPriority Number of positions to move 

   659         * @param [IN] aDirection Whether to increase or decrease priority. 

   660         *

   661         * @return one of the following error codes: 

   662         *         - KErrNone if the priority is changed sucessfully 

   663         *         - KErrNotFound if the specified server identity does not exists in settings storage 

   664         *         - KErrArgument if the specified priority is not valid (eg. negative)

   665         *

   666         */

   667         IMPORT_C TInt ChangePriority(

   668                         TInt64 aSlpId, 

   669                         TInt aPriority,

   670                         TBool aDirection

   671                         );

   672 

   673     /**

   674      * This method is used to retrieve all properties of server from SUPL settings storage

   675      * based on SLP identification.  

   676      *

   677      * @since S60 5.1 

   678      *

   679      * @param [IN] aSlpId SLP ID for which the parameters needs to be changed 

   680      * @param [OUT] aParamValues Parameter for which the value needs to be changed  

   681      * @ref CServerParams class

   682      *

   683      * @return one of the following error codes: 

   684      *         - KErrNone if SUPL settings are retrieved successfully.  

   685      *         - KErrNotFound if the specified server does not exists in the settings

   686      *

   687      */

   688     IMPORT_C TInt GetSlpInfoFromId(

   689             const TInt64 aSlpId, 

   690             CServerParams *aParamValues

   691     ) const;

   692 

   693 

   694     /**

   695      * This method is used to retrieve all properties of server from SUPL settings storage

   696      * based on SLP address.  

   697      *

   698      * @since S60 5.1 

   699      *

   700      * @param [IN] aServerAddress SLP address for which the parameters needs to be changed 

   701      * @param [OUT] aParamValues Parameter for which the value needs to be changed  

   702      * @ref CServerParams class

   703      *

   704      * @return one of the following error codes: 

   705      *         - KErrNone if SUPL settings are retrieved successfully.  

   706      *         - KErrNotFound if the specified server does not exists in the settings

   707      *

   708      */

   709     IMPORT_C TInt GetSlpInfoAddress(

   710             const TDesC& aServerAddress, 

   711             CServerParams *aParamValues

   712     ) const;

   713 

   714     /**

   715      * This method is used to retrieve all properties of default server from SUPL settings storage.  

   716      *

   717      * @since S60 5.1 

   718      *

   719      * @param [OUT] aParamValues Retrieves values from SUPL Settings storage 

   720      * @ref CServerParams class

   721      *

   722      * @return one of the following error codes: 

   723      *         - KErrNone if SUPL settings are retrieved successfully.  

   724      *         - KErrNotFound if the settings does not have any server entry 

   725      *

   726      */

   727     IMPORT_C TInt GetDefaultServer(

   728             CServerParams *aParamValues

   729     ) const;

   730 

   731     /**

   732      * This method is used to retrieve number of server entries present in SUPL settings. 

   733      *

   734      * @since S60 5.1 

   735      *

   736      * @param [OUT] aCount Number of SLP entries 

   737      *

   738      * @return one of the following error codes: 

   739      *         - KErrNone if number of SLP entries are calculated 

   740      *         - KErrNotFound if the settings does not have any server entry 

   741      *

   742      */

   743     IMPORT_C TInt SlpCount(

   744             TInt& aCount 

   745     );

   746 

   747     /**

   748      * This method is used check whether server entry exists or not based on SLP

   749      * identification 

   750      *

   751      * @since S60 5.1 

   752      *

   753      * @param [IN] aSlpId SLP identification 

   754      *

   755      * @return one of the following codes: 

   756      *         - ETrue if server entry exists in settings 

   757      *         - EFalse if server entry does not exists in settings 

   758      *

   759      */

   760     IMPORT_C TBool IsSlpExists(

   761             const TInt64 aSlpId 

   762     );

   763 

   764     /**

   765      * This method is used check whether server entry exists or not based on SLP

   766      * address 

   767      *

   768      * @since S60 5.1 

   769      *

   770      * @param [IN] aServerAddress Server address 

   771      *

   772      * @return one of the following codes: 

   773      *         - ETrue if server entry exists in settings 

   774      *         - EFalse if server entry does not exists in settings 

   775      *

   776      */

   777     IMPORT_C TBool IsSlpExists(

   778             const TDesC& aServerAddress 

   779     );

   780 

   781     /**

   782      * This synchronous method is used to retrieve properties of all servers from SUPL settings storage.  

   783      * This method retrieves all properties for each server.

   784      *

   785      * @since S60 5.1 

   786      *

   787      * @param [OUT] aParamValues Array of retrieved server entries 

   788      * @ref CServerParams class

   789      *

   790      * @return one of the following error codes: 

   791      *         - KErrNone if SUPL settings are retrieved successfully.  

   792      *         - KErrNotFound if the settings does not have any server entry 

   793      *

   794      */

   795     IMPORT_C TInt GetAllSlp(

   796             RPointerArray<CServerParams>& aParamValues

   797     ) const;

   798 

   799     /**

   800      * This method is used to retrieve properties of all servers from SUPL settings storage.  

   801      * This method retrieves all properties for each server.

   802      *

   803      * @since S60 5.1 

   804      *

   805      * @param [OUT] aParamValues Array of retrieved server entries 

   806      * @ref CServerParams class

   807      *

   808      * @return one of the following error codes: 

   809      *         - KErrNone if SUPL settings are retrieved successfully.  

   810      *         - KErrNotFound if the settings does not have any server entry 

   811      *

   812      */

   813     IMPORT_C TInt GetAllSlp(

   814             RPointerArray<CServerParams>& aParamValues,

   815             TRequestStatus& aStatus

   816     ) const;

   817 

   818 

   819     /**

   820      * This method enables or disables the fall back in SUPL settings.  If the fallback enabled,

   821      * if the SUPL session fails with default server or with the sever mentioned then fallback will

   822      * happen to next server in the list or to the server address generated from IMSI depending

   823      * on the failure type.  If the SUPL session has failed due to connection problem with server,

   824      * then fallback will happen to the address generated from IMSI.  In all other failures,

   825      * fallback will happen to the next server in the list.

   826      *

   827      * @since S60 5.1 

   828      *

   829      * @param [IN] aFallBack Indicates whether the fallback needs to be enabled or disabled 

   830      *

   831      * @return one of the following error codes: 

   832      *         - KErrNone if the fallback value changed sucessfully 

   833      *         - KErrGeneral if the fallback is enabled when only one server entry is present

   834      *         - KErrGeneral if changing SUPL settings has failed 

   835      */

   836     IMPORT_C TInt SetFallBack(TBool aFallBack);

   837 

   838     /**

   839      * This method retrieves the fallback value from SUPL settings storage.

   840      *

   841      * @since S60 5.1 

   842      *

   843      * @param [OUT] aFallBack Retrived fallback value 

   844      *

   845      * @return one of the following error codes: 

   846      *         - KErrNone if the fallback value retrieved sucessfully 

   847      */

   848     IMPORT_C TInt GetFallBack(TBool& aFallBack) const;

   849 

   850     /**

   851      * This method is used to retrieve properties of all active triggers. 

   852      *

   853      * @since S60 5.2 

   854      *

   855      * @param [OUT] aParamValues Array of retrieved trigger parameters.Ownership remains with client. 

   856      * @ref CTriggerParams class

   857      *

   858      * @return one of the following error codes: 

   859      *         - KErrNone if active trigger parameters are retrieved successfully.  

   860      *         - KErrNotFound if there are no active triggers 

   861      *           otherwise system wide error codes. 

   862      *

   863      */

   864     IMPORT_C TInt GetTriggerParams(

   865             RPointerArray<CTriggerParams>& aParamValues

   866     ) const;

   867     /**

   868      * This method is used to retrieve properties of a given session trigger. 

   869      *

   870      * @since S60 5.2 

   871      *

   872      * @param [IN] aSessionId Session identifier to get paramater of particular session.

   873      * @param [OUT] aParamValues Trigger Parameter.Ownership remains with client. 

   874      * @ref CTriggerParams class

   875      *

   876      * @return one of the following error codes: 

   877      *         - KErrNone if active trigger parameters are retrieved successfully.  

   878      *         - KErrNotFound if there is no active session with given id 

   879      *         - KErrArgument if aParamValues is NULL.

   880      *           otherwise system wide error codes. 

   881      */

   882     

   883     IMPORT_C TInt GetTriggerParams( TInt64 aSessionId,

   884                                      CTriggerParams*& aParamValues ) const;

   885           

   886 

   887     /*

   888      * Sets Notification status of particular session

   889      *

   890      * @since S60 5.2 

   891      * @param [IN] aSessionId Session identifier to get/change paramater of particular session 

   892      * @param [IN] aTriggerNotificationStaus  Indicates whether notification needs to be shown or

   893      * not after every trigger fired

   894      *

   895      * @return following error codes

   896      *      - KErrNone if successful

   897      *      - KErrNotFound if session is not found

   898      *           otherwise system wide error codes. 

   899      */

   900 	IMPORT_C TInt SetNotificationStatus(

   901 	            TInt64 aSessionId,

   902                 TBool aTriggerNotificationStatus

   903                 );

   904 	/*

   905 	 * Cancels given ongoing triggering session

   906 	 *

   907 	 * @since S60 5.2 

   908 	 * @param [IN] aSessionId Session identifier 

   909 	 *

   910 	 * @return following error codes

   911 	 *      - KErrNone if successful

   912 	 *      - KErrNotFound if session is not found

   913 	 *           otherwise system wide error codes. 

   914 	 */

   915 	IMPORT_C TInt CancelTriggerSession( TInt64 aSessionId );

   916 	

   917 	/**

   918 	 * This method can be used to obtain the default IAP configured.

   919 	 *

   920 	 * @since S60 5.2

   921 	 *

   922 	 * @param [OUT] aIapName a will hold, on successful completion, the default IAP name that was configured 

   923 	 * This can have maximum size of 100 characters.

   924 	 * @return one of the following error codes

   925 	 *  - KErrNone if method completed successfully

   926 	 *  - KErrOverflow if the descriptor is too small to hold the HSLP address 

   927 	 *  - KErrArgument if argument passed is of length zero

   928 	 */

   929 

   930 	IMPORT_C TInt GetDefaultIAPName(TDes& aIapName);

   931     

   932     private: // New functions

   933         

   934     private:

   935         // By default, prohibit copy constructor

   936         CSuplSettings( const CSuplSettings& );

   937         // Prohibit assigment operator

   938         CSuplSettings& operator= ( const CSuplSettings& );

   939 

   940     protected:    // Data

   941 //    private:    // Data

   942         /** 

   943          * Pointer to notifiers, needed to listen to SUPL settings change

   944          * events

   945          */

   946         CSuplSettingsNotifier*        iSettingsNotifier;

   947         /*

   948          * Pointer to notifiers, needed to listen to SUPL Settings Db Change

   949          */

   950         CSuplSettingsNotifier*        iSettingsDBChangeNotifier;

   951         /**  Pointer to CSuplSettingsEngine to all settings functions */

   952         CSuplSettingsEngine*         iSettingsEngine;

   953         

   954         CSuplSessionNotifier*        iSessionNotifier;

   955         /** To store and retun status for Initialize method */

   956         TRequestStatus  iStatus;

   957         /** To store whether settings are locked or not */

   958         TBool iLocked;

   959     };

   960 

   961 #endif      // __EPOS_CSUPLSETTINGS_H__

   962 

   963 // End of File