/*

* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  S60 SUPL Terminal Initiation API

*

*/

/*! \file epos_suplterminal.h

    \brief S60 SUPL Terminal Initiation API

*/

#ifndef __EPOS_SUPLTERMINAL_H__

#define __EPOS_SUPLTERMINAL_H__

#include <e32std.h>

#include <lbspositioninfo.h>

#include <epos_suplterminalqop.h>

#include <epos_suplterminaltrigger.h>

#include <epos_suplparameters.h>

// Forward declarations

class CSuplSubSessnPtrHolder;

class CSuplSettings;

class CSuplTerminalParams;

/**

 * This class is used to establish connection and to close connection

 * to terminal resident SUPL Server.  This class contains methods for 

 * connecting to SUPL Server, to close connection to SUPL Server and 

 * get SUPL Terminal Initiation API version number. 

 * After the connection has been established, its handle is passed as a 

 * parameter to the Open method of RSuplTerminalSubSession to create 

 * a "sub-session".

 * Client should close connection to SUPL Server when connection is no longer

 * required.

 */

class RSuplTerminalServer : public RSessionBase

	{

public:

    /**

     * Constructor for RSuplTerminalServer

     */

	IMPORT_C RSuplTerminalServer();

    /**

     * Creates a connection with  SUPL Server. If there is no other

     * connection when this is called, the method will start the server.

     * If client tries to connect again with the same instance before 

     * closing previous connection, it panics with panic code 

     * ESuplServerHandleNotClosed.

     *

     * @return following error codes 

     *

     *      - KErrNone when a link has been successfully established with SUPL Server.

     *      - KErrNotFound if server executable is not found to start a SUPL Server

     *      - KErrNotSupported if version of client API is not compatible 

     *		  with SUPL Server or if SUPL feature is not enabled in the terminal.

     *      - KErrPermissionDenied if client does not have CommDD capability

     */

	IMPORT_C TInt Connect();

    /**

     * Closes a connection with the SUPL Server. A client must 

     * ensure that all sub-sessions are closed and all outstanding requests 

     * are cancelled before the connection to SUPL Server is closed.

     */

	IMPORT_C void Close();

    /**

     * Obtains the current version number of the SUPL Terminal Initiation API.

     *

     * @return the version of the client API.

     */

	IMPORT_C TVersion Version() const;

    /**

     * Asynchronous method to creates a connection with SUPL Server. If there is no other

     * connection when this is called, the method will start the server.

     * If client tries to connect again with the same instance before 

     * closing previous connection, it panics with panic code 

     * ESuplServerHandleNotClosed.

     *

     * This method can complete the request issued by client with the following error codes 

     *      - KErrNone when a link has been successfully established with SUPL Server.

     *      - KErrNotFound if server executable is not found to start a SUPL Server

     *      - KErrNotSupported if version of client API is not compatible 

     *		  with SUPL Server or if SUPL feature is not enabled in the terminal.

     *      - KErrPermissionDenied if client does not have CommDD capability

     */

	IMPORT_C TInt Connect(TRequestStatus& aStatus);

private:

	void ConstructL();

	void Destruct();

	static TInt StartServer();

private:

	/** Unused variable for future expansion. */

	TAny* iReserved;

	};

/**

 * This class is used to make request to determine the position information, 

 * to request additional position information such as assistance data for A-GPS 

 * and to retrieve position information. Client can optionally specify Quality

 * of Position (QoP) while requesting for position determination. 

 * Before using the class, a connection must have already been established with the 

 * SUPL Server. This class also has methods to open subsession, 

 * to cancel outstanding position determination request and to close 

 * sub-session to SUPL Server.

 * All methods in this class, except Close, panics with ESuplServerBadHandle if

 * connection to SUPL Server is not established.

 *

 * @see RSuplTerminalServer

 */

class RSuplTerminalSubSession : public RSubSessionBase

	{

public :

	/**

	 * For differentiating request between Supl Service Versions 

	 *

	 */

	enum TSuplServiceType

	    {

	    ESUPL_1_0 = 1,

	    ESUPL_2_0

	    }; 

public:

    /**

     * Constructor for RSuplTerminalSubSession

     *

     */

	IMPORT_C RSuplTerminalSubSession();

    /**

     * Opens a sub-session to the SUPL Server. 

     * Client can request for position determination, can request for procedure to

     * get assistance data and retrieve position information through sub-session.

     * Panic ESuplServerHandleNotClosed occurs if sub-session is already opened 

     * @param [IN] aSuplServer is a connected session with SUPL Server.

     * @param [IN] aSuplService is a supl service version to be used 

     * @return Following error codes:

     *      -  KErrNone if subsession creation is sucessful.

     *      -  KErrServerBusy if SUPL Server has taken too long to accept a request

     *      -  KErrPermissionDenied if client does not have CommDD capability

     *      -  KErrNoMemory if there is no memory

     * 

     */

	IMPORT_C TInt Open(

					RSuplTerminalServer& aSuplServer, 

					TSuplServiceType aSuplService=ESUPL_1_0);

    /**

     * This is an asynchronous request to SUPL Server to determine position 

     * information or to determine additional positioning information such as

     * assistance data.

     * Client can have only one outstanding asynchronous request per sub-session.  

     *

     * Parameter aQop is of type @ref TSuplTerminalQop and can be used by the Terminal 

     * Initiation API client to specify the desired quality of position. Client can specify

     * horizontal accuracy, vertical accuracy, maximum location age and response time using this

     * parameter. 

     *

     * Parameter aSETCaps can be used to restrict the positioning technologies 

     * to be used in subsequent positioning determination request by the current client.

     * Parameter aSETCaps takes constant values defined in epos_suplterminalconstants.h

     * and additional constants can be introduced for positioning technologies not in 

     * mentioned in the list. This parameter has a default value of zero in 

     * which case any of the position technology can be used to determine the position

     * informatioin.

     * Following are the currently defined constant values:

     *      -  KGpsSETAssisted	=   0x0001,

     *      -  KGpsSETBased  	=  	0x0002,

     *      -  KAutonomousGps 	=  	0x0004,

     *      -  KAFLT 			=  	0x0008,

     *      -  KECID   		    =  	0x0010,

     *      -  KEOTD  			= 	0x0020,

     *      -  KOTDOA 			=   0x0040,

     *      -  KCID 			=   0x0080,

     *

     * 

     * Client can use more than one option from the above table using logical

     * 'OR' operator.

     *

     * Parameter aRequestId can be used by the Terminal Initiation API client 

     * to deliver a request identifier to the tunneled positioning protocol 

     * handler if needed. This is used by the client which is requesting for additional 

     * position information such as assistance data for A-GPS.  Tunneled protocol 

     * can use this value for example to match different assistance data requests 

     * and response received from SUPL Server. By default, the value of this parameter

     * is set to zero. It is client's responsibility to generate and keep track of 

     * this request identifier, if used.

     *

     * Parameter aFirstReq can be used by the Terminal Initiation API client to indicate 

     * whether the request is the first request in the subsession or not. By default, this

     * is set to ETrue to indicate that the request is the first one.  For 

     * second request onwards this parameter should be set to EFalse to indicate that the 

     * request is not the first one. 

     *

     * Since this is an asynchronous call, the client has to wait for status on 

     * aStatus parameter to know the result of position determination.

     *

     * Client can cancel this request using RSuplTerminalSubSession::CancelRunSession.

     * Before a client closes a sub-session, it must ensure that all 

     * outstanding requests have been cancelled. In particular, after the client 

     * has invoked the CancelRunSession() method, it must wait until SUPL Server has 

     * reported that the request has indeed been cancelled.

     * Panic ESuplDuplicateRequest occurs if there is already an outstanding request

     * for the sub session. 

     *

     * @param [OUT] aStatus to return result code 

     * @param [IN] aQop Desired quality of position 

     * @param [IN] aSETCaps will hold positioning technologies than can be used

     * @param [IN] aRequestId will hold request identifier to match assistance data request/response 

     * @param [IN] aFirstReq will indicate whether the request is the first one or not 

     * @return aStatus will have 

     *         - KErrNone if session is completed sucessfully.  

     *         - KErrCancel if the request was successfully cancelled

     *         - KErrTimedOut in case of SUPL session timeout

     *         - KErrNoMemory if there is no memory

     *         - KErrArgument if there is error in the arguments passed

     *         - KErrCompletion if position determination cannot be completed successfuly

     *         - KErrNotReady if SUPL server is not ready to determine position information, 

     *           client can retry after sometime.

     *         - KErrServerTerminated if server got terminated due to some error

     *         - KSuplPositionPresent if position is determined but SUPL Session could not be

     *					 completed successfully

     *         - KErrGeneral for all other errors

     */

	IMPORT_C void RunSession(

					TRequestStatus& aStatus, 

					TSuplTerminalQop& aQop, 

					TInt aSETCaps=0, 

					TInt aRequestId=0, 

					TBool aFirstReq=ETrue);

    /**

     * This is an synchronous request to SUPL server to determine position 

     * information or to determine additional positioning information.

     *

     * Parameter aQop is of type @ref TSuplTerminalQop and can be used by the Terminal 

     * Initiation API client to specify the desired quality of position. Client can specify

     * horizontal accuracy, vertical accuracy, maximum location age and response time using this

     * parameter. 

     *

     * Parameter aSETCaps can be used to restrict the positioning technologies 

     * to be used in subsequent positioning determination requests by the current client.

     * Parameter aSETCaps takes constant values defined in epos_suplterminalconstants.h 

     * and additional constants can be introduced for positioning technologies not in 

     * mentioned in the list. This parameter has a default value of zero in 

     * which case any of the position technology can be used to determine the position

     * informatioin.

     * Following are the currently defined constant values:

     *      -  KGpsSETAssisted	=   0x0001,

     *      -  KGpsSETBased  	=  	0x0002,

     *      -  KAutonomousGps 	=  	0x0004,

     *      -  KAFLT 			=  	0x0008,

     *      -  KECID   		    =  	0x0010,

     *      -  KEOTD  			= 	0x0020,

     *      -  KOTDOA 			=   0x0040,

     *      -  KCID 			=   0x0080,

     *

     * 

     * Client can use more than one option from the above table using logical

     * 'OR' operator.

     *

     * Parameter aRequestId can be used by the Terminal Initiation API client 

     * to deliver a request identifier to the tunneled positioning protocol 

     * handler if needed. This is used by the client which is requesting for additional 

     * position information such as assistance data for A-GPS. Tunneled protocol 

     * can use this value for example to match different assistance data requests 

     * and response received from SUPL Server. By default, value of this parameter

     * is set to zero. It is client's responsibility to generate and keep track of 

     * this request identifier, if used.

     *

     * Parameter aFirstReq can be used by the Terminal Initiation API client to indicate 

     * whether the request is the first request in the subsession or not. By default, this

     * is set to ETrue to indicate that the request is the first one.  For 

     * second request onwards this parameter should be set to EFalse to indicate that the 

     * request is not the first one. 

     *

     * @param [IN] aQop Desired quality of position 

     * @param [IN] aSETCaps will hold positioning technologies than can be used

     * @param [IN] aRequestId will hold request identifier to match assistance data request/response 

     * @param [IN] aFirstReq will indicate whether the request is the first one or not 

     * @return one of the following error codes: 

     *         - KErrNone if session is completed sucessfully.  

     *         - KErrTimedOut in case of SUPL session timeout

     *         - KErrNoMemory if there is no memory

     *         - KErrArgument if there is error in the arguments passed

     *         - KErrCompletion if position determination cannot be completed successfuly

     *         - KErrNotReady if SUPL server is not ready to determine position information

     *         - KErrServerTerminated if server got terminated due to some error

     *         - KSuplPositionPresent if position is determined but SUPL Session could not be

     *					 completed successfully

     *		   - KErrNotSupported if SUPL is disabled

     *         - KErrGeneral for all other errors

     */

	IMPORT_C TInt RunSession(

					TSuplTerminalQop& aQop, 

					TInt aSETCaps=0, 

					TInt aRequestId=0, 

					TBool aFirstReq=ETrue);

    /**

     * This is an asynchronous request to SUPL Server to determine position 

     * information or to determine additional positioning information such as

     * assistance data.

     * Client can have only one outstanding asynchronous request per sub-session.  

     *

     * Parameter aSETCaps can be used to restrict the positioning technologies 

     * to be used in subsequent positioning determination request by the current client.

     * Parameter aSETCaps takes constant values defined in epos_suplterminalconstants.h

     * and additional constants can be introduced for positioning technologies not

     * mentioned in the list. This parameter has a default value of zero in 

     * which case any of the position technology can be used to determine the position

     * informatioin.

     * Following are the currently defined constant values:

     *      -  KGpsSETAssisted	=   0x0001,

     *      -  KGpsSETBased  	=  	0x0002,

     *      -  KAutonomousGps 	=  	0x0004,

     *      -  KAFLT 			=  	0x0008,

     *      -  KECID   		    =  	0x0010,

     *      -  KEOTD  			= 	0x0020,

     *      -  KOTDOA 			=   0x0040,

     *      -  KCID 			=   0x0080,

     *

     * 

     * Client can use more than one option from the above table using logical

     * 'OR' operator.

     *

     * Parameter aRequestId can be used by the Terminal Initiation API client 

     * to deliver a request identifier to the tunneled positioning protocol 

     * handler if needed. This is used by the client which is requesting for additional 

     * position information such as assistance data for A-GPS. Tunneled protocol 

     * can use this value for example to match different assistance data requests 

     * and response received from SUPL Server. By default, value of this parameter

     * is set to zero. It is client's responsibility to generate and keep track of 

     * this request identifier, if used.

     *

     *

     * Parameter aFirstReq can be used by the Terminal Initiation API client to indicate 

     * whether the request is the first request in the subsession or not. By default, this

     * is set to ETrue to indicate that the request is the first one.  For 

     * second request onwards this parameter should be set to EFalse to indicate that the 

     * request is not the first one. 

     *

     * Since this is an asynchronous call, client has to wait for status on 

     * aStatus parameter to know the result of position determination.

     *

     * Client can cancel this request using RSuplTerminalSubSession::CancelRunSession.

     * Before a client closes a sub-session, it must ensure that all 

     * outstanding requests have been cancelled. In particular, after the client 

     * has invoked the CancelRunSession() method, it must wait until SUPL Server has 

     * reported that the request has indeed been cancelled.

     * Panic ESuplDuplicateRequest occurs if there is already an outstanding request

     * for the sub session. 

     *

     * @param [OUT] aStatus to return result code 

     * @param [IN] aSETCaps will hold positioning technologies than can be used

     * @param [IN] aRequestId will hold request identifier to match assistance data request/response 

     * @param [IN] aFirstReq will indicate whether the request is the first one or not 

     * @return aStatus will have 

     *         - KErrNone if session is completed sucessfully.  

     *         - KErrCancel if the request was successfully cancelled

     *         - KErrTimedOut in case of SUPL session timeout

     *         - KErrNoMemory if there is no memory

     *         - KErrArgument if there is error in the arguments passed

     *         - KErrCompletion if position determination cannot be completed successfuly

     *         - KErrNotReady if SUPL Server is not ready to determine position information, 

     *         	 client can retry after sometime.

     *         - KErrServerTerminated if server got terminated due to some error

     *         - KSuplPositionPresent if position is determined but SUPL Session could not be

     *			 completed successfully

     *         - KErrGeneral for all other errors

     */

	IMPORT_C void RunSession(

					TRequestStatus& aStatus, 

					TInt aSETCaps=0, 

					TInt aRequestId=0, 

					TBool aFirstReq=ETrue);

    /**

     * This is an synchronous request to SUPL Server to determine position 

     * information or to determine additional positioning information.

     *

     * Parameter aSETCaps can be used to restrict the positioning technologies 

     * to be used in subsequent positioning determination requests by the current client.

     * Parameter aSETCaps takes constant values defined in epos_suplterminalconstants.h 

     * and additional constants can be introduced for positioning technologies not in 

     * mentioned in the list. This parameter has a default value of zero in 

     * which case any of the position technology can be used to determine the position

     * informatioin.

     * Following are the currently defined constant values:

     *      -  KGpsSETAssisted	=   0x0001,

     *      -  KGpsSETBased  	=  	0x0002,

     *      -  KAutonomousGps 	=  	0x0004,

     *      -  KAFLT 			=  	0x0008,

     *      -  KECID   		    =  	0x0010,

     *      -  KEOTD  			= 	0x0020,

     *      -  KOTDOA 			=   0x0040,

     *      -  KCID 			=   0x0080,

     *

     * 

     * Client can use more than one option from the above table using logical

     * 'OR' operator.

     *

     * Parameter aRequestId can be used by the Terminal Initiation API client 

     * to deliver a request identifier to the tunneled positioning protocol 

     * handler if needed. This is used by the client which is requesting for additional 

     * position information such as assistance data for A-GPS. Tunneled protocol 

     * can use this value for example to match different assistance data requests 

     * and response received from SUPL server. By default, value of this parameter

     * is set to zero. It is client's responsibility to generate and keep track of 

     * this request identifier, if used.

     *

     * Parameter aFirstReq can be used by the Terminal Initiation API client to indicate 

     * whether the request is the first request in the subsession or not. By default, this

     * is set to ETrue to indicate that the request is the first one.  For 

     * second request onwards this parameter should be set to EFalse to indicate that the 

     * request is not the first one. 

     *

     * @param [IN] aSETCaps will hold positioning technologies than can be used

     * @param [IN] aRequestId will hold request identifier to match assistance data request/response 

     * @param [IN] aFirstReq will indicate whether the request is the first one or not 

     * @return one of the following error codes: 

     *         - KErrNone if session is completed sucessfully.  

     *         - KErrTimedOut in case of SUPL session timeout

     *         - KErrNoMemory if there is no memory

     *         - KErrArgument if there is error in the arguments passed

     *         - KErrCompletion if position determination cannot be completed successfuly

     *         - KErrNotReady if SUPL Server is not ready to determine position information

     *         - KErrServerTerminated if server got terminated due to some error

     *         - KSuplPositionPresent if position is determined but SUPL Session could not be

     *					completed successfully

     *         - KErrGeneral for all other errors

     */

	IMPORT_C TInt RunSession(

					TInt aSETCaps=0, 

					TInt aRequestId=0, 

					TBool aFirstReq=ETrue);

    /**

     * This is an synchronous method for retrieving position information  

     * determined during RSuplTerminalSubSession::RunSession(). This method should 

     * be called after RunSession is completed with KErrNone or with KSuplPositionPresent.

     * The parameter aPositionInfo is of type TPositionInfoBase defined by 

     * Location Acquisition API. It is possible to pass any class that is 

     * derived from TPositionInfoBase. But class types supported are 

     * TPositionInfo and HPositionGenericInfo defined in Location Acquisition API.

     * Using HPositionGenericInfo client can specify and retrieve extended 

     * position information. Client can specify field it wants to retrieve by setting 

     * identifiers of the requested fields in the HPositionGenericInfo object using 

     * HPositionGenericInfo::SetRequestedField method. 

     * Fields currently supported are:

     *      - EPositionFieldHorizontalSpeed

     *      - EPositionFieldHorizontalSpeedError

     *      - EPositionFieldVerticalSpeed

     *      - EPositionFieldVerticalSpeedError

     *

     * If the position determined during @ref RunSession() does not meet the quality criteria 

     * specified by the client, @p KSuplPositionQualityLoss is returned for @ref GetPosition().

     * But client will still be able to get the position information if @ref RunSession()

     * is completed with @p KErrNone. Quality of position in @ref RunSession()

     * is optional and returning @p KSuplPositionQualityLoss error code is applicable only

     * if client has mentioned QoP when invoking @ref RunSession().

     *

     * @param [OUT] aPositionInfo will hold, on successful completion, position information.

     * @return following error codes:

     *      -  KErrNone if position information is present

     *      -  KErrNotFound for following reasons: 

     *          - Position information is not available 

     *          - GetPosition is called before RunSession() 

     *          - RunSession() is not completed with KErrNone.

     *			- GetPosition is called after StartSuplTriggerSession()

     *      -  KErrPositionBufferOverflow if memory allocated by client for

     *      HPositionGenericInfo object is not enough to hold requested fields.

     *      -  KErrNotSupported if the field specified with HPositionGenericInfo 

     *      is not supported or if any other class derived from TPositionInfoBase, 

     *      other than TPositionInfo and HPositionGenericInfo, is used with this method.

     *      - KSuplPositionQualityLoss if the position information does not meet the quality 

     *      criteria specified by the client when invoking @ref RunSession() 

     *

     */

	IMPORT_C TInt GetPosition(TPositionInfoBase& aPositionInfo);

    /**

     * Closes a sub-session with the SUPL Server. This must be called when 

     * the RSuplTerminalSubSession sub-session is no longer required. 

     * All the outstanding requests must be cancelled before closing

     * sub-session.

     *

     */

	IMPORT_C void Close();

    /**

     * Cancels an outstanding asynchronous position determination, RunSession(), 

     * request. Canceling requests is typically attempted when an client 

     * is closing down.

     *

     */

	IMPORT_C void CancelRunSession();

    /**

     * Retrieves list of SUPL server propertis configured. Client can use the retrieved SUPL

     * server properties to specify the server address @ref RunSession() 

     * @param [OUT] aSlpList  

     * @return Following error codes:

     *      -  KErrNone if server list is retrieved successfully 

     *      -  KErrPermissionDenied if client does not have CommDD capability

     *      -  KErrNoMemory if there is no memory