inc/FLocLocationProvider.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FLocLocationProvider.h
  20  * @brief       This is the header file for the %LocationProvider class.
  21  *
  22  * This header file contains the declarations of the %LocationProvider class.
  23  */
  24
  25 #ifndef _FLOC_LOCATION_PROVIDER_H_
  26 #define _FLOC_LOCATION_PROVIDER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FLocTypes.h>
  30
  31 namespace Tizen { namespace Locations
  32 {
  33 class LocationCriteria;
  34 class Location;
  35 class ILocationProviderListener;
  36
  37 /**
  38 * @class        LocationProvider
  39 * @brief        This class provides methods to get locations and enable region monitoring.
  40 *
  41 * @since 2.0
  42 *
  43 * @final        This class is not intended for extension.
  44 *
  45 * The %LocationProvider class is a fundamental module that provides location-based services: location providing and region monitoring.
  46 * The location provider is constructed with a location criteria and offers the services trying to satisfy it in a best-effort manner.
  47 * An application gets locations by simply calling the GetLocation() method, or requesting asynchronous location updates with the
  48 * StartLocationUpdatesByInterval() and StartLocationUpdatesByDistance() methods. An application can also register regions by calling the
  49 * AddMonitoringRegion() method to be notified when moving into or out of regions. It gets asynchronous location updates and notifications
  50 * from the region monitoring by assigning a listener, which implements the ILocationProviderListener interface, to the location provider.
  51 *
  52 * @see          LocationCriteria
  53 */
  54 class _OSP_EXPORT_ LocationProvider
  55         : public Tizen::Base::Object
  56 {
  57 public:
  58         /**
  59         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after
  60         * calling this constructor.
  61         *
  62         * @since 2.0
  63         */
  64         LocationProvider(void);
  65
  66         /**
  67         * This destructor overrides Tizen::Base::Object::~Object().
  68         *
  69         * @since 2.0
  70         */
  71         virtual ~LocationProvider(void);
  72
  73         /**
  74         * Initializes this instance of %LocationProvider with the specified @c criteria and @c listener.
  75         *
  76         * An application chooses the desired service quality based on its scenario and constructs the location provider with the specified
  77         * @c criteria. The desired accuracy for locations is a configurable property of LocationCriteria.
  78         * The location provider tries to provides locations and services based on the specified @c criteria.
  79         *
  80         * The @c listener is notified on asynchronous location updates or region monitoring events.
  81         *
  82         * @since 2.0
  83         *
  84         * @return       An error code
  85         * @param[in]    criteria        The desired location criteria
  86         * @param[in]    listener        The listener to register
  87         * @exception    E_SUCCESS       The method is successful.
  88         * @exception    E_SYSTEM        A system error has occurred.
  89         */
  90         result Construct(const LocationCriteria& criteria, ILocationProviderListener& listener);
  91
  92         /**
  93         * Requests the location updates service with the specific @c interval.
  94         *
  95         * Once the location updates have started and the location provider has fixed the current location, the location is delivered
  96         * to the listener by calling the ILocationProviderListener::OnLocationUpdated() method.
  97         * The location provider is trying to provide accurate locations as requested in the criteria, but locations updated by the location provider
  98         * do not always fall into the requested accuracy level. It provides locations in low-grade accuracy if that is all it can offer
  99         * or can not even provide locations when it hardly fixes the current location. The location provider notifies the listener whenever the accuracy
 100         * level of ongoing updates are changed by calling the ILocationProviderListener::OnAccuracyChanged() method.
 101         *
 102         * The location updates can be paused by the location provider when the application is unable to point locations out to the user
 103         * for the moment. This is possible for the following situations:
 104         *  - The application is not running in foreground.
 105         *  - The screen is off.
 106         * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener.
 107         * It resumes the paused location updates when the application gets out of the situations.
 108         * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method.
 109         *
 110         * The change in the service status that the location provider is providing are notified to the listener
 111         * by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() method.
 112         *
 113         * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods,
 114         * the location provider cancels the prior request and restarts the updates with the specified parameter.
 115         *
 116         * @since 2.0
 117         * @privlevel    public
 118         * @privilege http://tizen.org/privilege/location
 119         *
 120         * @return       An error code
 121         * @param[in]    interval        The update interval in seconds
 122         * @exception    E_SUCCESS       The method is successful.
 123         * @exception    E_INVALID_ARG   The specified @c interval is less than @c 1.
 124         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 125         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 126         * @see          StopLocationUpdates()
 127         */
 128         result StartLocationUpdatesByInterval(int interval);
 129
 130         /**
 131         * Requests the location updates service with the specific @c distance filter.
 132         *
 133         * Once the location updates have started, the initial location is delivered soon after it becomes available to the listener
 134         * by calling the ILocationProviderListener::OnLocationUpdated() method. Then the location provider updates subsequent locations
 135         * when it changes over the specified @c distance.
 136         *
 137         * The location updates can be paused by the location provider when the application is unable to point locations out to the user
 138         * for the moment. This is possible for the following situations:
 139         *  - The application is not running in foreground.
 140         *  - The screen is off.
 141         * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener.
 142         * It resumes the paused location updates when the application gets out of the situations.
 143         * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method.
 144         *
 145         * Along with the service status, the accuracy level that the location provider is currently providing
 146         * is notified to the listener on changes by calling the ILocationProviderListener::OnLocationUpdateStatusChanged()
 147         * and ILocationProviderListener::OnAccuracyChanged() methods respectively.
 148         *
 149         * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods,
 150         * the location provider cancels the prior request and restarts the updates with the specified parameter.
 151         *
 152         * @since 2.0
 153         * @privlevel    public
 154         * @privilege http://tizen.org/privilege/location
 155         *
 156         * @return       An error code
 157         * @param[in]    distance        The distance in meters
 158         * @exception    E_SUCCESS       The method is successful.
 159         * @exception    E_INVALID_ARG   The specified @c distance is less than or equal to @c 0.0 or @c NaN.
 160         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 161         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 162         * @see          StopLocationUpdates()
 163         */
 164         result StartLocationUpdatesByDistance(double distance);
 165
 166         /**
 167         * Stops the location updates.
 168         *
 169         * @since 2.0
 170         *
 171         * @return       An error code
 172         * @exception    E_SUCCESS       The method is successful.
 173         * @exception    E_INVALID_OPERATION     The location updates has not been requested.
 174         * @see          StartLocationUpdatesByInterval()
 175         * @see          StartLocationUpdatesByDistance()
 176         */
 177         result StopLocationUpdates(void);
 178
 179         /**
 180         * Keeps the location updates awake or not.
 181         *
 182         * The location provider can pause the ongoing location updates when the application is unable to point locations out to the user
 183         * for the moment. This is possible for the following situations:
 184         *  - The application is not running in foreground.
 185         *  - The screen is off.
 186         *
 187         * To get the location updates all the time, the application should use the StartLocationUpdatesByInterval() or
 188         * StartLocationUpdatesByDistance() methods together with the %KeepLocationUpdateAwake() method turning the flag @c enable on.
 189         * The application should be cautious about doing so since it can make the system awake
 190         * during the location updates.
 191         *
 192         * @since 2.0
 193         * @privlevel    public
 194         * @privilege http://tizen.org/privilege/location and http://tizen.org/privilege/power @n
 195         *                               Both privileges are required.
 196         *
 197         * @return       An error code
 198         * @param[in]    enable  Set to @c true to keep the location updates awake, @n
 199         *                                                       else @c false
 200         * @exception    E_SUCCESS       The method is successful.
 201         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 202         * @see          StartLocationUpdatesByInterval()
 203         * @see          StartLocationUpdatesByDistance()
 204         * @see          StopLocationUpdates()
 205         */
 206         result KeepLocationUpdateAwake(bool enable);
 207
 208         /**
 209         * Adds a region for monitoring.
 210         *
 211         * A region is defined by a center point and a radius.
 212         * The location provider starts the region monitoring service until all regions are removed. When it detects a movement that crosses the
 213         * boundary of a registered region, it notifies the application by calling ILocationProviderListener::OnRegionEntered() or
 214         * ILocationProviderListener::OnRegionLeft() with the region identifier that is returned by the %AddMonitoringRegion() method.
 215         * The altitude of @c regionCenter is not considered in monitoring.
 216         *
 217         * Along with the service status, the accuracy level that the location provider is currently providing
 218         * is notified to the listener on changes by calling the ILocationProviderListener::OnRegionMonitoringStatusChanged()
 219         * and ILocationProviderListener::OnAccuracyChanged() methods respectively.
 220         *
 221         * Note that, the monitoring service can sometimes makes the system awake by running costly positioning devices.
 222         *
 223         * @since 2.0
 224         * @privlevel    public
 225         * @privilege http://tizen.org/privilege/location and http://tizen.org/privilege/power @n
 226         *                               Both privileges are required.
 227         *
 228         * @return       An error code
 229         * @param[in]    regionCenter    The center coordinate of the region
 230         * @param[in]    radius  The monitoring radius in meters
 231         * @param[out]   regionId        The ID for the registered region
 232         * @exception    E_SUCCESS       The method is successful.
 233         * @exception    E_INVALID_ARG   The @c radius is not in the supported monitoring raidus range, which currently is [50, 100000] meters, @n
 234         *                                                               else the @c radius or the latitude or the longitude of @c regionCenter is @c NaN
 235         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 236         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 237         * @see          RemoveMonitoringRegion()
 238         * @see          RemoveAllMonitoringRegions()
 239         */
 240         result AddMonitoringRegion(const Coordinates& regionCenter, double radius, RegionId& regionId);
 241
 242         /**
 243         * Removes the monitoring region.
 244         *
 245         * @since 2.0
 246         *
 247         * @return       An error code
 248         * @param[in]    regionId        The region ID to remove
 249         * @exception    E_SUCCESS       The method is successful.
 250         * @exception    E_INVALID_ARG   The specified @c regionId is invalid.
 251         * @see          AddMonitoringRegion()
 252         */
 253         result RemoveMonitoringRegion(RegionId regionId);
 254
 255         /**
 256         * Removes all regions that the location provider monitors.
 257         *
 258         * @since 2.0
 259         *
 260         * @see          AddMonitoringRegion()
 261         */
 262         void RemoveAllMonitoringRegions(void);
 263
 264         /**
 265         * Gets the current service status of the location updates.
 266         *
 267         * The location updates service is started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance()
 268         * method. If an application has not made valid requests for the service, the %GetLocationUpdateStatus() method returns @c LOC_SVC_STATUS_IDLE.
 269         * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnLocationUpdateStatusChanged() listener method.
 270         *
 271         * @since 2.0
 272         * @return       The current service status of the location updates
 273         */
 274         LocationServiceStatus GetLocationUpdateStatus(void) const;
 275
 276         /**
 277         * Gets the current service status of the region monitoring.
 278         *
 279         * The region monitoring service is started by calling the AddMonitoringRegion() method.
 280         * If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE.
 281         * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnRegionMonitoringStatusChanged() listener method.
 282         *
 283         * @since 2.0
 284         * @return       The current status of the region monitoring service
 285         */
 286         LocationServiceStatus GetRegionMonitoringStatus(void) const;
 287
 288         /**
 289         * Gets the accuracy level that the location provider is currently providing.
 290         *
 291         * If an application has not made valid requests for location updates and region monitoring, the %GetCurrentAccuracy() method
 292         * returns @c LOC_ACCURACY_INVALID.
 293         * Otherwise, it returns the accuracy level last notified by the ILocationProviderListener::OnAccuracyChanged() listener method.
 294         *
 295         * @since 2.0
 296         * @return       The current location accuracy
 297         */
 298         LocationAccuracy GetCurrentAccuracy(void) const;
 299
 300         /**
 301         * Gets a current location.
 302         *
 303         * An application can simply get the current location with the %GetLocation() method.
 304         *
 305         * The location provider runs and waits for positioning systems to fix the current location as requested in the criteria.
 306         * If it is not fixed in some time, this method call is aborted and returns a location in low-grade accuracy or even
 307         * an invalid location with an @c E_LOCATION_UNAVAILABLE error.
 308         *
 309         * @since 2.0
 310         * @privlevel    public
 311         * @privilege http://tizen.org/privilege/location
 312         *
 313         * @return       The current location
 314         * @param[in]    criteria        The desired location criteria
 315         * @exception    E_SUCCESS       The method is successful.
 316         * @exception    E_LOCATION_UNAVAILABLE  The location provider fails to fix the current location.
 317         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 318         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 319         * @exception    E_SYSTEM        A system error has occurred.
 320         * @remarks      This method call takes time as the location provider runs and waits for positioning system.
 321         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 322         */
 323         static Location GetLocation(const LocationCriteria& criteria);
 324
 325         /**
 326         * Gets the last known location.
 327         *
 328         * The %GetLastKnownLocation() method returns the last location the system keeps.
 329         * It is always a good idea to prefer using this method than requesting current locations
 330         * since using the last location preserves the location provider from running costly positioning systems.
 331         *
 332         * @since 2.0
 333         * @privlevel    public
 334         * @privilege http://tizen.org/privilege/location
 335         *
 336         * @return       The last location
 337         * @exception    E_SUCCESS       The method is successful.
 338         * @exception    E_LOCATION_UNAVAILABLE  The last location is unavailable.
 339         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 340         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 341         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 342         */
 343         static Location GetLastKnownLocation(void);
 344
 345 private:
 346         //
 347         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 348         //
 349         LocationProvider(const LocationProvider& rhs);
 350
 351         //
 352         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 353         //
 354         LocationProvider& operator =(const LocationProvider& rhs);
 355
 356 private:
 357         class _LocationProviderImpl* __pImpl;
 358         friend class _LocationProviderImpl;
 359 }; //LocationProvider
 360 }} // Tizen::Locations
 361 #endif // _FLOC_LOCATION_PROVIDER_H_