path: root/inc/FLocLocationProvider.h

//
// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

/**
 * @file	FLocLocationProvider.h
 * @brief	This is the header file for the %LocationProvider class.
 *
 * This header file contains the declarations of the %LocationProvider class.
 */

#ifndef _FLOC_LOCATION_PROVIDER_H_
#define _FLOC_LOCATION_PROVIDER_H_

#include <FBaseObject.h>
#include <FLocTypes.h>

namespace Tizen { namespace Locations
{
class LocationCriteria;
class Location;
class ILocationProviderListener;

/**
* @class	LocationProvider
* @brief	This class provides methods to get locations and enable region monitoring.
*
* @since 2.0
*
* @final	This class is not intended for extension.
*
* The %LocationProvider class is a fundamental module that provides location-based services: location providing and region monitoring.
* The location provider is constructed with a location criteria and offers the services trying to satisfy it in a best-effort manner.
* An application gets locations by simply calling the GetLocation() method, or requesting asynchronous location updates with the
* StartLocationUpdatesByInterval() and StartLocationUpdatesByDistance() methods. An application can also register regions by calling the
* AddMonitoringRegion() method to be notified when moving into or out of regions. It gets asynchronous location updates and notifications
* from the region monitoring by assigning a listener, which implements the ILocationProviderListener interface, to the location provider.
*
* @see		LocationCriteria
*/
class _OSP_EXPORT_ LocationProvider
	: public Tizen::Base::Object
{
public:
	/**
	* The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after
	* calling this constructor.
	*
	* @since 2.0
	*/
	LocationProvider(void);

	/**
	* This destructor overrides Tizen::Base::Object::~Object().
	*
	* @since 2.0
	*/
	virtual ~LocationProvider(void);

	/**
	* Initializes this instance of %LocationProvider with the specified @c criteria and @c listener.
	*
	* An application chooses the desired service quality based on its scenario and constructs the location provider with the specified
	* @c criteria. The desired accuracy for locations is a configurable property of LocationCriteria.
	* The location provider tries to provides locations and services based on the specified @c criteria.
	*
	* The @c listener is notified on asynchronous location updates or region monitoring events.
	*
	* @since 2.0
	*
	* @return	An error code
	* @param[in]	criteria	The desired location criteria
	* @param[in]	listener	The listener to register
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_SYSTEM	A system error has occurred.
	*/
	result Construct(const LocationCriteria& criteria, ILocationProviderListener& listener);

	/**
	* Requests the location updates service with the specific @c interval.
	*
	* Once the location updates have started and the location provider has fixed the current location, the location is delivered
	* to the listener by calling the ILocationProviderListener::OnLocationUpdated() method.
	* The location provider is trying to provide accurate locations as requested in the criteria, but locations updated by the location provider
	* do not always fall into the requested accuracy level. It provides locations in low-grade accuracy if that is all it can offer
	* or can not even provide locations when it hardly fixes the current location. The location provider notifies the listener whenever the accuracy
	* level of ongoing updates are changed by calling the ILocationProviderListener::OnAccuracyChanged() method.
	*
	* The location updates can be paused by the location provider when the application is unable to point locations out to the user
	* for the moment. This is possible for the following situations:
	*  - The application is not running in foreground.
	*  - The screen is off.
	* In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener.
	* It resumes the paused location updates when the application gets out of the situations.
	* To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method.
	*
	* The change in the service status that the location provider is providing are notified to the listener
	* by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() method.
	*
	* If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods,
	* the location provider cancels the prior request and restarts the updates with the specified parameter.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location
	*
	* @return	An error code
	* @param[in]	interval	The update interval in seconds
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_INVALID_ARG	The specified @c interval is less than @c 1.
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @exception	E_USER_NOT_CONSENTED	The user blocks an application from using the location information.
	* @see		StopLocationUpdates()
	*/
	result StartLocationUpdatesByInterval(int interval);

	/**
	* Requests the location updates service with the specific @c distance filter.
	*
	* Once the location updates have started, the initial location is delivered soon after it becomes available to the listener
	* by calling the ILocationProviderListener::OnLocationUpdated() method. Then the location provider updates subsequent locations
	* when it changes over the specified @c distance.
	*
	* The location updates can be paused by the location provider when the application is unable to point locations out to the user
	* for the moment. This is possible for the following situations:
	*  - The application is not running in foreground.
	*  - The screen is off.
	* In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener.
	* It resumes the paused location updates when the application gets out of the situations.
	* To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method.
	*
	* Along with the service status, the accuracy level that the location provider is currently providing
	* is notified to the listener on changes by calling the ILocationProviderListener::OnLocationUpdateStatusChanged()
	* and ILocationProviderListener::OnAccuracyChanged() methods respectively.
	*
	* If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() methods,
	* the location provider cancels the prior request and restarts the updates with the specified parameter.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location
	*
	* @return	An error code
	* @param[in]	distance	The distance in meters
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_INVALID_ARG	The specified @c distance is less than or equal to @c 0.0 or @c NaN.
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @exception	E_USER_NOT_CONSENTED	The user blocks an application from using the location information.
	* @see		StopLocationUpdates()
	*/
	result StartLocationUpdatesByDistance(double distance);

	/**
	* Stops the location updates.
	*
	* @since 2.0
	*
	* @return	An error code
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_INVALID_OPERATION	The location updates has not been requested.
	* @see		StartLocationUpdatesByInterval()
	* @see		StartLocationUpdatesByDistance()
	*/
	result StopLocationUpdates(void);

	/**
	* Keeps the location updates awake or not.
	*
	* The location provider can pause the ongoing location updates when the application is unable to point locations out to the user
	* for the moment. This is possible for the following situations:
	*  - The application is not running in foreground.
	*  - The screen is off.
	*
	* To get the location updates all the time, the application should use the StartLocationUpdatesByInterval() or
	* StartLocationUpdatesByDistance() methods together with the %KeepLocationUpdateAwake() method turning the flag @c enable on.
	* The application should be cautious about doing so since it can make the system awake
	* during the location updates.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
	*				Both privileges are required.
	*
	* @return	An error code
	* @param[in]	enable	Set to @c true to keep the location updates awake, @n
	*							else @c false
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @see		StartLocationUpdatesByInterval()
	* @see		StartLocationUpdatesByDistance()
	* @see		StopLocationUpdates()
	*/
	result KeepLocationUpdateAwake(bool enable);

	/**
	* Adds a region for monitoring.
	*
	* A region is defined by a center point and a radius.
	* The location provider starts the region monitoring service until all regions are removed. When it detects a movement that crosses the
	* boundary of a registered region, it notifies the application by calling ILocationProviderListener::OnRegionEntered() or
	* ILocationProviderListener::OnRegionLeft() with the region identifier that is returned by the %AddMonitoringRegion() method.
	* The altitude of @c regionCenter is not considered in monitoring.
	*
	* Along with the service status, the accuracy level that the location provider is currently providing
	* is notified to the listener on changes by calling the ILocationProviderListener::OnRegionMonitoringStatusChanged()
	* and ILocationProviderListener::OnAccuracyChanged() methods respectively.
	*
	* Note that, the monitoring service can sometimes makes the system awake by running costly positioning devices.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
	*				Both privileges are required.
	*
	* @return	An error code
	* @param[in]	regionCenter	The center coordinate of the region
	* @param[in]	radius	The monitoring radius in meters
	* @param[out]	regionId	The ID for the registered region
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_INVALID_ARG	The @c radius is not in the supported monitoring raidus range, which currently is [50, 100000] meters, @n
	*								else the @c radius or the latitude or the longitude of @c regionCenter is @c NaN
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @exception	E_USER_NOT_CONSENTED	The user blocks an application from using the location information.
	* @see		RemoveMonitoringRegion()
	* @see		RemoveAllMonitoringRegions()
	*/
	result AddMonitoringRegion(const Coordinates& regionCenter, double radius, RegionId& regionId);

	/**
	* Removes the monitoring region.
	*
	* @since 2.0
	*
	* @return	An error code
	* @param[in]	regionId	The region ID to remove
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_INVALID_ARG	The specified @c regionId is invalid.
	* @see		AddMonitoringRegion()
	*/
	result RemoveMonitoringRegion(RegionId regionId);

	/**
	* Removes all regions that the location provider monitors.
	*
	* @since 2.0
	*
	* @see		AddMonitoringRegion()
	*/
	void RemoveAllMonitoringRegions(void);

	/**
	* Gets the current service status of the location updates.
	*
	* The location updates service is started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance()
	* method. If an application has not made valid requests for the service, the %GetLocationUpdateStatus() method returns @c LOC_SVC_STATUS_IDLE.
	* Otherwise, it returns the service status notified last by the ILocationProviderListener::OnLocationUpdateStatusChanged() listener method.
	*
	* @since 2.0
	* @return	The current service status of the location updates
	*/
	LocationServiceStatus GetLocationUpdateStatus(void) const;

	/**
	* Gets the current service status of the region monitoring.
	*
	* The region monitoring service is started by calling the AddMonitoringRegion() method.
	* If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE.
	* Otherwise, it returns the service status notified last by the ILocationProviderListener::OnRegionMonitoringStatusChanged() listener method.
	*
	* @since 2.0
	* @return	The current status of the region monitoring service
	*/
	LocationServiceStatus GetRegionMonitoringStatus(void) const;

	/**
	* Gets the accuracy level that the location provider is currently providing.
	*
	* If an application has not made valid requests for location updates and region monitoring, the %GetCurrentAccuracy() method
	* returns @c LOC_ACCURACY_INVALID.
	* Otherwise, it returns the accuracy level last notified by the ILocationProviderListener::OnAccuracyChanged() listener method.
	*
	* @since 2.0
	* @return	The current location accuracy
	*/
	LocationAccuracy GetCurrentAccuracy(void) const;

	/**
	* Gets a current location.
	*
	* An application can simply get the current location with the %GetLocation() method.
	*
	* The location provider runs and waits for positioning systems to fix the current location as requested in the criteria.
	* If it is not fixed in some time, this method call is aborted and returns a location in low-grade accuracy or even
	* an invalid location with an @c E_LOCATION_UNAVAILABLE error.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location
	*
	* @return	The current location
	* @param[in]	criteria	The desired location criteria
	* @exception	E_SUCCESS	The method is successful.
	* @exception	E_LOCATION_UNAVAILABLE	The location provider fails to fix the current location.
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @exception	E_USER_NOT_CONSENTED	The user blocks an application from using the location information.
	* @exception	E_SYSTEM	A system error has occurred.
	* @remarks	This method call takes time as the location provider runs and waits for positioning system.
	*			If the method is called from the application's main thread, it makes the application unresponsive until it returns.
	*			If an application wants to be responsive, especially within the user interaction, it should use this method
	*			in a separated thread using Tizen::Base::Runtime::Thread class,
	*			rather than in the application's main thread which handles the ui events.
	* @remarks	The specific error code can be accessed using the GetLastResult() method.
	*/
	static Location GetLocation(const LocationCriteria& criteria);

	/**
	* Gets the last known location.
	*
	* The %GetLastKnownLocation() method returns the last location the system keeps.
	* It is always a good idea to prefer using this method than requesting current locations
	* since using the last location preserves the location provider from running costly positioning systems.
	*
	* @since 2.0
	* @privilege %http://tizen.org/privilege/location
	*
	* @return	The last location
	* @exception	E_SUCCESS	The method is successful.
	* @exception    E_LOCATION_UNAVAILABLE  The last location is unavailable.
	* @exception	E_PRIVILEGE_DENIED	The application does not have the privilege to call this method.
	* @exception	E_USER_NOT_CONSENTED	The user blocks an application from using the location information.
	* @remarks     The specific error code can be accessed using the GetLastResult() method.
	*/
	static Location GetLastKnownLocation(void);

private:
	//
	// The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
	//
	LocationProvider(const LocationProvider& rhs);

	//
	// The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
	//
	LocationProvider& operator =(const LocationProvider& rhs);

private:
	class _LocationProviderImpl* __pImpl;
	friend class _LocationProviderImpl;
}; //LocationProvider
}} // Tizen::Locations
#endif // _FLOC_LOCATION_PROVIDER_H_