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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @internalComponent

    19  @prototype

    20 */

    21 

    22 

    23 #ifndef LBS_SUPL_PSY_ADAPTATION_H

    24 #define LBS_SUPL_PSY_ADAPTATION_H

    25 

    26 #include <e32std.h>

    27 #include <e32base.h>

    28 #include <lbs.h>

    29 #include "lbsnetinternalapi.h"

    30 #include "lbsnetinternalmsgtypes.h"

    31 

    32 

    33 /**

    34 The MLbsSuplPsyAdaptationObserver class is used in partnership with

    35 CLbsSuplPsyAdaptation. The observer interface is used by LBS to provide 

    36 responses to requests made by the SUPL PSY via CLbsSuplPsyAdaptation. 

    37 

    38 Although all the interface methods in the MLbsSuplPsyAdaptationObserver

    39 are synchronous they should return quickly. If required, the SUPL PSY should 

    40 internally queue the responses and process them asynchronously. 

    41 

    42 @see CLbsSuplPsyAdaptation

    43 */

    44 class MLbsSuplPsyAdaptationObserver

    45 	{

    46 public:

    47 	virtual TVersion Version() = 0;

    48 	

    49 	virtual void OnLocationUpdate(TUint aRequestId, TPositionInfoBase& aPosition, TInt aReason) = 0;

    50 

    51 	/**

    52 	LBS issues a single call to OnSessionComplete() to close a session and return the final 

    53 	result code to the SUPL PSY. 

    54 

    55 	The aReason parameter indicates the overall success or failure for the request. 

    56 

    57 	The request ID parameter identifies the session that is being closed. This ID is allocated when

    58 	a new request is created: 

    59 

    60 	In normal situations, OnSessionComplete() will be invoked when the overall request has

    61 	finished. OnSessionComplete() can also be used by LBS to terminate a request if a protocol 

    62 	conflict has arisen. For example, the local SUPL subsystem or a remote SUPL Server is unable to 

    63 	simultaneously perform two requests (for example a TerminalBased AGPS session is active).

    64 

    65 	@param aRequestId The Id of the request being closed. 

    66 

    67 	@param aReason Reason for the completion of the request. KErrNone if the request is successfully

    68 	       completed, or one of a range of error codes otherwise. 

    69 	*/

    70 	virtual void OnSessionComplete(TUint aRequestId, TInt aReason) = 0;

    71 	};

    72 

    73 

    74 /**

    75 The SUPL PSY adaptation interface is a point to point interface between the SUPL PSY and 

    76 the Netowrk Gateway and allows the SUPL PSY to ask a remote SUPL Server for the position of 

    77 the device. As the interface is point to point, only one instance is allowed and must be shared 

    78 between one or more SUPL PSYs. It is the responsibility of the SUPL PSY(s) to combine multiple 

    79 requests coming from multiple users.

    80 

    81 The CLbsSuplPsyAdaptation class is used in partnership with MLbsSuplPsyAdaptationObserver. 

    82 LBS responds to requests from the SUPL PSY via that observer class. 

    83 

    84 Although all the interface methods in the class are synchronous they must return immediately.

    85 When the SUPL PSY makes a request via CLbsSuplPsyAdaptation the LBS subsystem must

    86 queue the request internally and return control to the caller immediately. Afterwards, when

    87 the SUPL Server provides a response LBS uses the corresponding notification method in the

    88 MLbsSuplPsyAdaptationObserver class. 

    89 

    90 The interface is a temporary solution and should be removed (or incorporated into the SUPL PSY) 

    91 once a common codeline is established.

    92 

    93 The interface, even though declared as internalAll, MUST be used by the SUPL PSY EXCLUSIVELY.

    94 It MUST NOT be used by the Generic Network PSY, or any other components.

    95 

    96 @see MLbsSuplPsyAdaptationObserver 

    97 */

    98 NONSHARABLE_CLASS(CLbsSuplPsyAdaptation) : public CActive, public MLbsNetChannelObserver

    99 	{

   100 public:

   101 	static CLbsSuplPsyAdaptation * NewL(MLbsSuplPsyAdaptationObserver& aObserver);

   102 	~ CLbsSuplPsyAdaptation ();

   103 	

   104 	/**

   105 	RequestLocationUpdate() should be used by the SUPL PSY to request a SUPL Server to

   106 	calculate the current location of the handset and return it to the terminal. 

   107 

   108 	When the location information is received from the SUPL Server it is being forwarded to 

   109 	the SUPl PSY via the method MLbsSuplPsyAdaptationObserver::OnLocationUpdate().

   110 

   111 	The position information returned is network calculated and is normally

   112 	expected to be an approximate location only. For example, related to the position

   113 	of the current serving cell. It may also be a position calculated by the network with

   114 	the assistance of the terminal (the terminal sends measurements to the network).

   115 

   116 	This method automatically cancels any active location request and

   117 	replaces it with the new request. The CancelLocationRequest() method is used when the

   118 	SYPL PSY wants to a cancel request but does not immediately wish to replace it with

   119 	another.

   120 

   121 	The aRequestId parameter is generated by the SUPL PSY and is used to connect all

   122 	corresponding responses and further requests. The same request ID must be used the 

   123 	SUPL PSY if it wishes to cancel the request. Similarly, the same request ID must also

   124 	be supplied by LBS when it responds to the SUPL PSY 

   125 	via the MLbsSuplPsyAdaptationObserver::OnLocationUpdate() method.

   126 

   127 	The request ID is also passed by the LBS subsystem when it closes a session via the

   128 	method MLbsSuplPsyAdaptationObserver::OnSessionComplete().

   129 

   130 	@param aRequestId The Id of the location request. This is generated by the SUPL PSY

   131 	       and must be used by LBS when it returns the obtained position information. 

   132 

   133 	@param aProtocolModuleId The Id of the protocol Module to be used.

   134 	@param aProtocolModuleId The Id of the protocol Module to be used.

   135 	@param aNewClient		 Indicates the first request from a new client.

   136 

   137 

   138 	@see CLbsAdmin

   139 	@see MLbsSuplPsyAdaptationObserver::OnSessionComplete()

   140 	@see MLbsSuplPsyAdaptationObserver::OnLocationUpdate()

   141 	@see CancelLocationRequest

   142 	*/

   143 	void RequestLocationUpdate(TUint aRequestId, TBool aNewClient, TUid aProtocolModule);

   144 

   145 	/**

   146 	This method attempts to cancel a request to obtain the location

   147 	of the terminal. The previous request will have been initiated by calling

   148 	RequestLocationUpdate()

   149 

   150 	Note: If the SUPL PSY wishes to stop the location request and immediately issue a 

   151 	new location request it should issue a subsequent call to RequestLocationUpdate().

   152 	Submitting a new location request, automatically cancels any outstanding transfer.

   153 

   154 	In some circumstances, LBS may still return the associated position to the SUPl PSY.

   155 	This situation can occur when the cancel request is performed after a point where it 

   156 	is no longer possible to stop the request being sent.

   157 

   158 	@param aRequestId The Id of the network location request to be cancelled.

   159 	@param aReason Indicates why the LBS subsystem wants the terminate the request. 

   160 

   161 	@see RequestLocationUpdate() 

   162 	@see MLbsSuplPsyAdaptationObserver::OnLocationUpdate()

   163 	*/

   164 	void CancelLocationRequest(TUint aRequestId, TInt aReason);

   165 

   166     virtual void ProcessNetChannelMessage(RLbsNetChannel::TLbsNetChannelId aChannelId, const TLbsNetInternalMsgBase& aMessage);

   167 

   168 private:

   169         /**

   170         * From CActive

   171         */

   172         void RunL();

   173 

   174         /**

   175         * From CActive

   176         */

   177         void DoCancel();

   178 

   179         /**

   180         * From CActive

   181         */

   182         TInt RunError( TInt aError );

   183 

   184         TLbsNetInternalMsgBase* CreateTLbsCellLocationRequestMsgL(TUint aRequestId, TBool aNewClient, TUid aProtocolModule);

   185 

   186 private:

   187 	CLbsSuplPsyAdaptation (MLbsSuplPsyAdaptationObserver& aObserver);

   188 	void ConstructL();

   189             /**

   190         * Construct HPositionGenericInfo and set requested fields

   191         */

   192         HPositionGenericInfo* ConstructGenericInfoL( 

   193             TInt aBufferSize = KPositionGenericInfoDefaultBufferSize ) const;

   194 

   195 private:

   196             // Callback function for get location request complete event

   197         MLbsSuplPsyAdaptationObserver& iObserver;

   198 

   199         RLbsNetChannel iPsyChannel;

   200 

   201         TLbsNetInternalMsgBase* iSentMsg;

   202         

   203         // position info

   204         TPositionInfoBase* iPositionInfo;

   205         

   206         TUint iRequestid;    

   207 

   208         TBool iLocRequest;

   209 	};

   210 

   211 	

   212 #endif // LBS_SUPL_PSY_ADAPTATION_H