1 /*

     2 * Copyright (c) 2006-2009 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:  An interface to Location Trail.

    15 *

    16 */

    17 

    18 #ifndef R_RLOCATIONTRAIL_H

    19 #define R_RLOCATIONTRAIL_H

    20 

    21 #include <e32base.h>

    22 #include <etel3rdparty.h>

    23 #include <LbsPosition.h>

    24 #include <rlocationmanager.h>

    25 #include <locationdatatype.h>

    26 

    27 typedef TPckg<TLocality> TLocalityPckg;

    28 

    29 /**

    30  *  RLocationManager class is used for creating a Location Manager session.

    31  *  Location Manager is used to start and stop the location trail, retrieve 

    32  *  location information and write the location information to images.

    33  *

    34  *  @lib LocationManager.lib

    35  *  @since S60 3.1

    36  */

    37 NONSHARABLE_CLASS( RLocationTrail ) : public RLocationManager

    38     {

    39 public:

    40     /**

    41      * Location trail states.

    42      */

    43     enum TTrailState

    44         {

    45         ETrailStopped,

    46         EWaitingGPSData,

    47         ESearchingGPS,

    48         ETrailStarted,

    49         ETrailStopping,

    50         ETrailStarting

    51         };

    52     enum TTrailCaptureSetting

    53     	{

    54     	EOff,

    55     	ECaptureNetworkInfo,

    56     	ECaptureAll 

    57     	};

    58         

    59 public:

    60 	IMPORT_C RLocationTrail();

    61 	

    62 	IMPORT_C ~RLocationTrail();

    63 

    64     /**

    65      * Starts recording location information to location trail.

    66      * @since S60 3.2

    67      * @param aState, an enumeration of ECaptureNetworkInfo  

    68      * (only cell ID stored) and ECaptureAll 

    69      * (GPS coordinates and cell ID stored).

    70      * @return KErrNone if successful, otherwise one of the other 

    71      *         system-wide error codes.

    72      */

    73     IMPORT_C TInt StartLocationTrail(TTrailCaptureSetting aState);

    74     

    75     /**

    76      * Stops recording location information to location trail.

    77      * @since S60 3.1

    78      * @param None.

    79      * @return KErrNone if successful, otherwise one of the other 

    80      *         system-wide error codes.

    81      */

    82     IMPORT_C TInt StopLocationTrail();

    83     

    84     /**

    85      * Retuns the current state of the location trail.

    86      * @since S60 3.1

    87      * @param aState, The state of the trail is returned.

    88      * @return KErrNone if successful, otherwise one of the other 

    89      *         system-wide error codes.

    90      */

    91     IMPORT_C TInt GetLocationTrailState( TTrailState& aState );

    92     

    93     /**

    94      * Get notification when the location trail state changes.

    95      * @since S60 3.1

    96      * @param aStatus, The request status. 

    97      * @return None.

    98      */

    99     IMPORT_C void NotifyLocationTrailStateChange( TRequestStatus& aStatus ); 

   100     

   101     /**

   102      * Cancel notification request for the location trail state change.

   103      * @since S60 3.1

   104      * @param None.

   105      * @return None.

   106      */

   107     IMPORT_C void CancelNotificationRequest();    

   108     

   109     /**

   110      * Get location by time stamp. If the TLocality for given time stamp is 

   111      * found from the trail, it is returned even if the data in it wouldn't 

   112      * be valid.

   113      * @since S60 3.1

   114      * @param aTimeStamp, Time stamp to get corresponding location.

   115      * @param aPosition, Position value returned.

   116      * @param aNetworkInfo, Network value returned.

   117      * @param aState, State of the trail at given time.

   118      * @return KErrNone if successful, otherwise one of the other 

   119      *         system-wide error codes.

   120      */                                

   121     IMPORT_C TInt RetrieveLocation( const TTime& aTimeStamp, 

   122     								TLocationData& aLocationData,

   123                                     TTrailState& aState );

   124 

   125     /**

   126      * Retrieve current location. If request is completed successfully, the 

   127      * result is returned via the aLocationInfo and aNetworkInfo arguments. 

   128      * The function is asynchronous, because it may take 

   129      * several minutes to get location information. 

   130      * @since S60 3.2

   131      * @param aStatus, The request status.

   132      * @param aLocationData, locationData encapsulates all location data

   133      * @return None.

   134      */

   135     IMPORT_C void CurrentLocation( TRequestStatus& aStatus, 

   136     							   TLocationData& aLocationData);					

   137                                    

   138     /**

   139      * Cancel asynchronous location request.

   140      * @since S60 3.1

   141      * @param None.

   142      * @return None.

   143      */

   144     IMPORT_C void CancelLocationRequest();

   145 

   146     /**

   147      * Get current trail capture setting.

   148      * @return EOff, ECaptureNetworkInfo or ECaptureAll

   149      */

   150     IMPORT_C TInt GetTrailCaptureSetting( TTrailCaptureSetting& aCaptureSetting );

   151     

   152 private:

   153 	TPckg<TLocationData>* iCurrentLocData;

   154     };

   155     

   156 #endif // R_RLOCATIONTRAIL_H

   157 

   158 //End of File