1 /*

     2 * Copyright (c) 2006-2007 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 the License "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:  Header file for location SAPI service implementation.

    15 *

    16 */

    17 

    18 #ifndef LOCATIONSERVICE_H

    19 #define LOCATIONSERVICE_H

    20 

    21 #include <lbs.h>

    22 class CGetLoc;

    23 /**

    24  * Identity for location SAPI lib 

    25  * This will be appended to requestor identity information stack received from the 

    26  * client and will be passed onto location server

    27  */

    28 

    29 _LIT(KIdentity,"Location SAPI");

    30 

    31 /**

    32  * Key for locating active objects associated with async request in registration table

    33  *

    34  * @ 0 for  Getlocation async Active object

    35  * @ 1 for Trace async active object

    36  */

    37  

    38 const TInt KARRAY_INDEX_GETLOCATION = 0 ;

    39 const TInt KARRAY_INDEX_TRACE       = 1 ; 

    40 

    41 

    42 

    43 /**

    44  * Key for locating location information in CLiwGenericParamList

    45  */

    46 _LIT8(KLongitudeKey,"Longitude") ;

    47 _LIT8(KLatitudeKey , "Latitude") ;

    48 _LIT8(KAltitudeKey , "Altitude") ;

    49 

    50 _LIT(KUnknown,"Unknown");

    51 

    52 /**

    53  * Default Update options

    54  */

    55 //Second

    56 const TInt KSSecond = 1000000;

    57 

    58 //Update interval

    59 const TInt KSUpdateInterval = KSSecond;

    60 

    61 //Update time out

    62 const TInt KSUpdateTimeOut = 15*KSSecond;

    63 

    64 //MaxAge

    65 const TInt KSMaxAge = 0;

    66 

    67 /**

    68  * Enums required for mathoperations

    69  */

    70 enum TMathOperationChoice

    71 	{

    72 	EDistance  = 0,

    73 	EBearingTo = 1,

    74 	EMove      = 2

    75 	};

    76 

    77 /**

    78  * Notification Type to be cancelled

    79  */

    80 enum TCancelParam

    81     {

    82 	ECancelGetLocation = 0,

    83 	ECancelTrace = 1

    84     }; 

    85 /**

    86  * Enumeration used to identify category of location information user intends to 

    87  * retrieve

    88  * Example: specifying EBasic user will get only longitude,latitude and altitude

    89  */

    90  enum TLocationInfoType

    91 	 {

    92 	 EBasicInfo = 0,

    93 	 EGenericInfo = 1	

    94 	 };

    95 

    96 /**

    97  * used by the caller of math operation to send input parameters 

    98  * after computation MathOperation wil fill in result field of this

    99  * struct.

   100  */

   101 struct _INPPARM

   102 	{

   103     //specifies option for mathoperation

   104 	TInt servicechoice;

   105 	//result of the computation

   106 	TReal32 result ;

   107 	//Source Coordinate for math operation

   108 	TCoordinate source;

   109 	//Destination Coordinate for math operation

   110 	TCoordinate destination ;

   111 	//In case of find bearingto following two should be supplied by the consumer

   112 	TReal32 bearing;

   113 	TReal32 distance;

   114 	

   115 	};

   116 

   117 typedef struct _INPPARM inpparam;

   118 

   119 

   120 

   121 /**

   122  *  Location callback interface, its pure interface class, application need to 

   123  *  Write there own callback derriving from this class.

   124  *  @Depenedency lbs.lib

   125  */

   126  

   127  class MLocationCallBack 

   128     {

   129     /**

   130      * Handles notifications caused by an asynchronous GetLocationL,

   131      * or by trace.

   132      *

   133      * @param aOutPos updated position got from location server

   134      * @return Success/Error code for the callback.

   135      *

   136      * @see HPositionGenericInfo in LbsPositionInfo.h for details

   137      *

   138      */

   139     public :

   140     virtual TInt HandleNotifyL(HPositionGenericInfo* aOutPos , TInt aError) = 0 ;

   141     };

   142 

   143 

   144 /**

   145  * CLocationService class : This is a wrapper class for the Functionalities 

   146  * offered by Location Retreival APIs.

   147  * In case of An Asynchronus request it has method which Instantiates and delegate 

   148  * the job to another class which  also opens new sub-session with

   149  * Location server.

   150  */ 

   151 

   152 

   153 class CLocationService : public CBase 

   154     {

   155     public :

   156 	    /**

   157         * Creates a new instance of a @ref CLocationService

   158         * @return The newly created CLocationService object

   159         */

   160 	    IMPORT_C static CLocationService *NewL() ;

   161 

   162 	     

   163 		 /*

   164 		  * @Destructor

   165 		  */

   166 	    virtual ~CLocationService() ; 

   167 

   168 	    /**

   169 	     * Methods on the  Core Location implementation

   170 	     */

   171 

   172 

   173 

   174 	    /**

   175 	     * Synchronous get location with update options returns current location of the user

   176 	     *

   177 	     * @param aPosinfobase input TPositionInfoBase object which will hold location details

   178 	     * @param aUpdateOpts updateoptions for synchronous calls 

   179 	     */

   180 	    IMPORT_C TInt GetLocationL( TPositionInfoBase* aPos ,

   181 	    							const TPositionUpdateOptions* aUpdateOpts= NULL ) ;

   182 	    							

   183 

   184 	    /**

   185 	     * Gets the current location of user asynchronosly calls the users callback handle on reciving 

   186 	     * location updates

   187 	     * @param aCallBack callback object after reciving the position updates 

   188 	     * @param aLocationInfoCategory specifying one of the enumeration in TLocationInfoType.

   189 	     * @param aFieldIdList specifies field of HPositionGenericInfo that user intend to retrieve.

   190 	     * @param aUpdateoptions update options for asynchronous requests.

   191 	     * @see Lsbcommon.h for details of TPositionFieldIdList and TPositionUpdateOptions

   192 	     */

   193 	    IMPORT_C TInt GetLocationL( MLocationCallBack* aCallBackObj ,

   194 	    							TInt aLocationInfoCategory = 0, 

   195 	    							TPositionFieldIdList aFieldIdList = NULL ,

   196 	    							const TPositionUpdateOptions* aUpdateopts = NULL

   197 	    							 );

   198 	    							

   199 	    /**

   200 	     * Gets module information of the Positioning module specified my aModuleId

   201 	     *

   202 	     * @param TPositionModuleId param to store the obtained module information

   203 	     *

   204 	     * @see lsbcommon.h for details of TPositionModuleInfoBase

   205 	     */								

   206 	    IMPORT_C TInt GetModuleInfo( TPositionModuleInfoBase& aModuleInfo ) const ;	

   207     

   208 	    /**

   209 	     * Performs mathoperations (move,distance,bearingto) by parsing contents of input param

   210 	     *							

   211 	     * @param aInput input paramater for math opertaions

   212 	     * 

   213 	     * @see inparam in this file for detailed math operation list

   214 	     */

   215 	       							

   216 

   217 	    IMPORT_C TInt MathOperation( inpparam& aInput );

   218 

   219 	    /**

   220 	     * Trace function traces users location changes any change in users current location is notificed 

   221 	     * to user via call back function

   222 	     *

   223 	     * @param aCallBackObj callback object after reciving location updates 

   224 	     * @param aLocationInfoCategory specifying one of the enumeration in TLocationInfoType.

   225 	     * @param aFiledList List of position fields that should be retrived 

   226 	     * @param aUpdateOptions update options for trace

   227 	     *

   228 	     * @see Lsbcommon.h for details of TPositionFieldIdList and TPositionUpdateOptions

   229 	     */ 

   230 

   231 	    IMPORT_C TInt TraceL(MLocationCallBack* aCallBackObj , 

   232 	    						TInt aLocationInfoCategory = 0,

   233 	    						TPositionFieldIdList aFiledList = NULL ,

   234 	    						const TPositionUpdateOptions* aUpateOptions= NULL );

   235 	    						

   236 

   237 	    /**

   238 	     * Method to cancell pending async request

   239 	     * 

   240 	     * aCancelparam cancellation type (trace,getlocation)

   241 	     *

   242 	     * @see TCancelParam for cancellation options

   243 	     */

   244 

   245 	     IMPORT_C TInt CancelOnGoingService( TInt aCancelparam ) ;

   246 	    

   247 	    /**

   248 	     * Method to fetch last known location from location server

   249 	     */

   250 

   251 	     TInt GetLastKnownLoc( TPosition& aResultPos ) ; 

   252 

   253 

   254 

   255 

   256 

   257     protected:

   258 	    /**

   259 	     * internal method to construct class members 

   260 	     */

   261 	    void ConstructL() ; 

   262 	    

   263 	    /**

   264 	     * Default constructor 

   265 	     */

   266 	    CLocationService() ;  

   267 	    

   268 	    /**

   269 	     * Method to initalise class memebers 

   270 	     */

   271 	    void DoInitialiseL() ;

   272 

   273 	    private :

   274 	    

   275 	    /**

   276 	     * Subsession used to fetch location information

   277 	     */

   278 

   279 	    RPositioner iPositioner;

   280 	    

   281 	    /**

   282 	     * Session used for getting location information

   283 	     */

   284 

   285 	    RPositionServer iPosServer;

   286 	    

   287 	    /**

   288 	     * Registration table for callbacks

   289 	     */

   290 	          

   291 	    RPointerArray<CGetLoc> iRegTable; 

   292 	    TInt iIndex;

   293 

   294 	    

   295 	    /**

   296 	     * Module indtifier used by location server for getting location information

   297 	     */

   298 	    TPositionModuleId iModuleId ; 

   299 

   300     };

   301 

   302 

   303 #endif // LOCATIONSERVICE_H