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         * @privilege %http://tizen.org/privilege/location
 118         *
 119         * @return       An error code
 120         * @param[in]    interval        The update interval in seconds
 121         * @exception    E_SUCCESS       The method is successful.
 122         * @exception    E_INVALID_ARG   The specified @c interval is less than @c 1.
 123         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 124         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 125         * @see          StopLocationUpdates()
 126         */
 127         result StartLocationUpdatesByInterval(int interval);
 128
 129         /**
 130         * Requests the location updates service with the specific @c distance filter.
 131         *
 132         * Once the location updates have started, the initial location is delivered soon after it becomes available to the listener
 133         * by calling the ILocationProviderListener::OnLocationUpdated() method. Then the location provider updates subsequent locations
 134         * when it changes over the specified @c distance.
 135         *
 136         * The location updates can be paused by the location provider when the application is unable to point locations out to the user
 137         * for the moment. This is possible for the following situations:
 138         *  - The application is not running in foreground.
 139         *  - The screen is off.
 140         * In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener.
 141         * It resumes the paused location updates when the application gets out of the situations.
 142         * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method.
 143         *
 144         * Along with the service status, the accuracy level that the location provider is currently providing
 145         * is notified to the listener on changes by calling the ILocationProviderListener::OnLocationUpdateStatusChanged()
 146         * and ILocationProviderListener::OnAccuracyChanged() methods respectively.
 147         *
 148         * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods,
 149         * the location provider cancels the prior request and restarts the updates with the specified parameter.
 150         *
 151         * @since 2.0
 152         * @privilege %http://tizen.org/privilege/location
 153         *
 154         * @return       An error code
 155         * @param[in]    distance        The distance in meters
 156         * @exception    E_SUCCESS       The method is successful.
 157         * @exception    E_INVALID_ARG   The specified @c distance is less than or equal to @c 0.0 or @c NaN.
 158         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 159         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 160         * @see          StopLocationUpdates()
 161         */
 162         result StartLocationUpdatesByDistance(double distance);
 163
 164         /**
 165         * Stops the location updates.
 166         *
 167         * @since 2.0
 168         *
 169         * @return       An error code
 170         * @exception    E_SUCCESS       The method is successful.
 171         * @exception    E_INVALID_OPERATION     The location updates has not been requested.
 172         * @see          StartLocationUpdatesByInterval()
 173         * @see          StartLocationUpdatesByDistance()
 174         */
 175         result StopLocationUpdates(void);
 176
 177         /**
 178         * Keeps the location updates awake or not.
 179         *
 180         * The location provider can pause the ongoing location updates when the application is unable to point locations out to the user
 181         * for the moment. This is possible for the following situations:
 182         *  - The application is not running in foreground.
 183         *  - The screen is off.
 184         *
 185         * To get the location updates all the time, the application should use the StartLocationUpdatesByInterval() or
 186         * StartLocationUpdatesByDistance() methods together with the %KeepLocationUpdateAwake() method turning the flag @c enable on.
 187         * The application should be cautious about doing so since it can make the system awake
 188         * during the location updates.
 189         *
 190         * @since 2.0
 191         * @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
 192         *                               Both privileges are required.
 193         *
 194         * @return       An error code
 195         * @param[in]    enable  Set to @c true to keep the location updates awake, @n
 196         *                                                       else @c false
 197         * @exception    E_SUCCESS       The method is successful.
 198         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 199         * @see          StartLocationUpdatesByInterval()
 200         * @see          StartLocationUpdatesByDistance()
 201         * @see          StopLocationUpdates()
 202         */
 203         result KeepLocationUpdateAwake(bool enable);
 204
 205         /**
 206         * Adds a region for monitoring.
 207         *
 208         * A region is defined by a center point and a radius.
 209         * The location provider starts the region monitoring service until all regions are removed. When it detects a movement that crosses the
 210         * boundary of a registered region, it notifies the application by calling ILocationProviderListener::OnRegionEntered() or
 211         * ILocationProviderListener::OnRegionLeft() with the region identifier that is returned by the %AddMonitoringRegion() method.
 212         * The altitude of @c regionCenter is not considered in monitoring.
 213         *
 214         * Along with the service status, the accuracy level that the location provider is currently providing
 215         * is notified to the listener on changes by calling the ILocationProviderListener::OnRegionMonitoringStatusChanged()
 216         * and ILocationProviderListener::OnAccuracyChanged() methods respectively.
 217         *
 218         * Note that, the monitoring service can sometimes makes the system awake by running costly positioning devices.
 219         *
 220         * @since 2.0
 221         * @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
 222         *                               Both privileges are required.
 223         *
 224         * @return       An error code
 225         * @param[in]    regionCenter    The center coordinate of the region
 226         * @param[in]    radius  The monitoring radius in meters
 227         * @param[out]   regionId        The ID for the registered region
 228         * @exception    E_SUCCESS       The method is successful.
 229         * @exception    E_INVALID_ARG   The @c radius is not in the supported monitoring raidus range, which currently is [50, 100000] meters, @n
 230         *                                                               else the @c radius or the latitude or the longitude of @c regionCenter is @c NaN
 231         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 232         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 233         * @see          RemoveMonitoringRegion()
 234         * @see          RemoveAllMonitoringRegions()
 235         */
 236         result AddMonitoringRegion(const Coordinates& regionCenter, double radius, RegionId& regionId);
 237
 238         /**
 239         * Removes the monitoring region.
 240         *
 241         * @since 2.0
 242         *
 243         * @return       An error code
 244         * @param[in]    regionId        The region ID to remove
 245         * @exception    E_SUCCESS       The method is successful.
 246         * @exception    E_INVALID_ARG   The specified @c regionId is invalid.
 247         * @see          AddMonitoringRegion()
 248         */
 249         result RemoveMonitoringRegion(RegionId regionId);
 250
 251         /**
 252         * Removes all regions that the location provider monitors.
 253         *
 254         * @since 2.0
 255         *
 256         * @see          AddMonitoringRegion()
 257         */
 258         void RemoveAllMonitoringRegions(void);
 259
 260         /**
 261         * Gets the current service status of the location updates.
 262         *
 263         * The location updates service is started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance()
 264         * method. If an application has not made valid requests for the service, the %GetLocationUpdateStatus() method returns @c LOC_SVC_STATUS_IDLE.
 265         * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnLocationUpdateStatusChanged() listener method.
 266         *
 267         * @since 2.0
 268         * @return       The current service status of the location updates
 269         */
 270         LocationServiceStatus GetLocationUpdateStatus(void) const;
 271
 272         /**
 273         * Gets the current service status of the region monitoring.
 274         *
 275         * The region monitoring service is started by calling the AddMonitoringRegion() method.
 276         * If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE.
 277         * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnRegionMonitoringStatusChanged() listener method.
 278         *
 279         * @since 2.0
 280         * @return       The current status of the region monitoring service
 281         */
 282         LocationServiceStatus GetRegionMonitoringStatus(void) const;
 283
 284         /**
 285         * Gets the accuracy level that the location provider is currently providing.
 286         *
 287         * If an application has not made valid requests for location updates and region monitoring, the %GetCurrentAccuracy() method
 288         * returns @c LOC_ACCURACY_INVALID.
 289         * Otherwise, it returns the accuracy level last notified by the ILocationProviderListener::OnAccuracyChanged() listener method.
 290         *
 291         * @since 2.0
 292         * @return       The current location accuracy
 293         */
 294         LocationAccuracy GetCurrentAccuracy(void) const;
 295
 296         /**
 297         * Gets a current location.
 298         *
 299         * An application can simply get the current location with the %GetLocation() method.
 300         *
 301         * The location provider runs and waits for positioning systems to fix the current location as requested in the criteria.
 302         * If it is not fixed in some time, this method call is aborted and returns a location in low-grade accuracy or even
 303         * an invalid location with an @c E_LOCATION_UNAVAILABLE error.
 304         *
 305         * @since 2.0
 306         * @privilege %http://tizen.org/privilege/location
 307         *
 308         * @return       The current location
 309         * @param[in]    criteria        The desired location criteria
 310         * @exception    E_SUCCESS       The method is successful.
 311         * @exception    E_LOCATION_UNAVAILABLE  The location provider fails to fix the current location.
 312         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 313         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 314         * @exception    E_SYSTEM        A system error has occurred.
 315         * @remarks      This method call takes time as the location provider runs and waits for positioning system.
 316         *                       If the method is called from the application's main thread, it makes the application unresponsive until it returns.
 317         *                       If an application wants to be responsive, especially within the user interaction, it should use this method
 318         *                       in a separated thread using Tizen::Base::Runtime::Thread class,
 319         *                       rather than in the application's main thread which handles the ui events.
 320         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 321         */
 322         static Location GetLocation(const LocationCriteria& criteria);
 323
 324         /**
 325         * Gets the last known location.
 326         *
 327         * The %GetLastKnownLocation() method returns the last location the system keeps.
 328         * It is always a good idea to prefer using this method than requesting current locations
 329         * since using the last location preserves the location provider from running costly positioning systems.
 330         *
 331         * @since 2.0
 332         * @privilege %http://tizen.org/privilege/location
 333         *
 334         * @return       The last location
 335         * @exception    E_SUCCESS       The method is successful.
 336         * @exception    E_LOCATION_UNAVAILABLE  The last location is unavailable.
 337         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 338         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from using the location information.
 339         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 340         */
 341         static Location GetLastKnownLocation(void);
 342
 343 private:
 344         //
 345         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 346         //
 347         LocationProvider(const LocationProvider& rhs);
 348
 349         //
 350         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 351         //
 352         LocationProvider& operator =(const LocationProvider& rhs);
 353
 354 private:
 355         class _LocationProviderImpl* __pImpl;
 356         friend class _LocationProviderImpl;
 357 }; //LocationProvider
 358 }} // Tizen::Locations
 359 #endif // _FLOC_LOCATION_PROVIDER_H_