diff options
Diffstat (limited to 'inc')
| -rw-r--r-- | inc/FLocCoordinates.h | 281 | ||||
| -rw-r--r-- | inc/FLocILocationProviderListener.h | 200 | ||||
| -rw-r--r-- | inc/FLocLocation.h | 210 | ||||
| -rw-r--r-- | inc/FLocLocationCriteria.h | 144 | ||||
| -rwxr-xr-x | inc/FLocLocationProvider.h | 359 | ||||
| -rw-r--r-- | inc/FLocTypes.h | 83 | ||||
| -rw-r--r-- | inc/FLocations.h | 56 |
7 files changed, 1333 insertions, 0 deletions
diff --git a/inc/FLocCoordinates.h b/inc/FLocCoordinates.h new file mode 100644 index 0000000..c5d6096 --- /dev/null +++ b/inc/FLocCoordinates.h @@ -0,0 +1,281 @@ +// +// 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 FLocCoordinates.h +* @brief This is the header file for the %Coordinates class. +* +* This header file contains the declarations of the %Coordinates class. +*/ + +#ifndef _FLOC_COORDINATES_H_ +#define _FLOC_COORDINATES_H_ + +#include <FBaseObject.h> +#include <FLocTypes.h> + +namespace Tizen { namespace Base +{ +class String; +}} + +namespace Tizen { namespace Locations +{ + +/** +* @class Coordinates +* @brief This class represents a geographical point. +* +* @since 2.0 +* +* @final This class is not intended for extension. +* +* The %Coordinates class represents a geographical point specified by latitude, longitude, and altitude values and provides +* geographic calculations between two points. +* +* The latitude and longitude in decimal degrees are sometimes represented in degrees, minutes, and seconds format. For example, 40.1874 degrees +* can also be represented in "40:11.25"(40 degrees and 11.25 minutes) or "40:11:15.0" (40 degrees, 11 minutes and 15.0 seconds). +* This class provides methods for converting a coordinate value to degrees and minutes or degrees, minutes, and seconds representation. +*/ +class _OSP_EXPORT_ Coordinates + : public Tizen::Base::Object +{ +public: + /** + * Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number. + * + * An application should set values of the coordinates using Set() method to specify it. + * + * @since 2.0 + */ + Coordinates(void); + + /** + * Copying of objects using this copy constructor is allowed. + * + * @since 2.0 + * + * @param[in] rhs An instance of %Coordinates to copy + */ + Coordinates(const Coordinates& rhs); + + /** + * This destructor overrides Tizen::Base::Object::~Object(). + * + * @since 2.0 + */ + virtual ~Coordinates(void); + + /** + * Compares the calling instance with the specified instance for equality. + * + * @since 2.0 + * + * @return @c true if all the fields in the objects are equal, @n + * else @c false + * @param[in] rhs The object to compare + */ + virtual bool Equals(const Tizen::Base::Object& rhs) const; + + /** + * Gets the hash value of the calling instance. + * + * @since 2.0 + * + * @return The hash value of the calling instance + */ + virtual int GetHashCode(void) const; + + /** + * Sets the latitude, longitude, and altitude values of the coordinates. + * + * An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. + * Otherwise, the %Set() method returns an @c E_INVALID_ARG exception. + * + * @since 2.0 + * + * @return An error code + * @param[in] latitude The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0] + * @param[in] longitude The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0] + * @param[in] altitude The altitude of the coordinates in meters + * @exception E_SUCCESS This method is successful. + * @exception E_INVALID_ARG The specified @c latitude or @c longitude is invalid. + * @see GetLatitude() + * @see GetLongitude() + * @see GetAltitude() + */ + result Set(double latitude, double longitude, double altitude); + + /** + * Sets the latitude value of the coordinates. + * + * An application should specify latitude value in the valid range of [-90.0, +90.0]. + * Otherwise, the %SetLatitude() method returns an @c E_INVALID_ARG exception. + * + * @since 2.0 + * + * @return An error code + * @param[in] latitude The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0] + * @exception E_SUCCESS This method is successful. + * @exception E_INVALID_ARG The specified @c latitude is invalid. + * @see GetLatitude() + */ + result SetLatitude(double latitude); + + /** + * Sets the longitude value of the coordinates. + * + * An application should specify longitude value in the valid range of [-180.0, +180.0]. + * Otherwise, the %SetLongitude() method returns an @c E_INVALID_ARG exception. + * + * @since 2.0 + * + * @return An error code + * @param[in] longitude The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0] + * @exception E_SUCCESS This method is successful. + * @exception E_INVALID_ARG The specified @c longitude is invalid. + * @see GetLongitude() + */ + result SetLongitude(double longitude); + + /** + * Sets the altitude value of the coordinates. + * + * @since 2.0 + * + * @param[in] altitude The altitude of the coordinates in meters + * @see GetAltitude() + */ + void SetAltitude(double altitude); + + /** + * Gets the latitude value of the coordinates. + * + * @since 2.0 + * + * @return The latitude in decimal degrees within the range [-90.0, +90.0], @n + * else @c NaN if it is not available + * @see SetLatitude() + */ + double GetLatitude(void) const; + + /** + * Gets the longitude value of the coordinates. + * + * @since 2.0 + * + * @return The longitude in decimal degrees within the range [-180.0, +180.0], @n + * else @c NaN if it is not available + * @see SetLongitude() + */ + double GetLongitude(void) const; + + /** + * Gets the altitude value of the coordinates. + * + * @since 2.0 + * + * @return The altitude in meters, @n + * else @c NaN if it is not available + * @see SetAltitude() + */ + double GetAltitude(void) const; + + /** + * Calculates the azimuth value. + * + * The coordinates are the starting point and @c dest is the destination for the azimuth calculation. + * The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model. + * + * The altitude value is not considered in calculation. + * + * @since 2.0 + * + * @return The azimuth value in decimal degrees within the range [0.0, +360.0], @n + * else @c NaN if the latitude or the longitude of two points has an @c NaN value + * @param[in] dest The destination coordinates + */ + double GetAzimuth(const Coordinates& dest) const; + + /** + * Calculates the geodetic distance to the given coordinates. + * + * The distance calculation is based on the WGS84 ellipsoid model. + * + * The altitude value is not considered in calculation. + * + * @since 2.0 + * + * @return The distance to the given coordinates in meters, @n + * else @c NaN if the latitude or the longitude of two points has an @c NaN value + * @param[in] to The destination coordinates + */ + double GetDistanceTo(const Coordinates& to) const; + + /** + * Converts the coordinate value into string. + * + * An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the result string. + * + * @since 2.0 + * + * @return An error code + * @param[in] degree The coordinate in degrees within the range [-180.0, +180.0] + * @param[in] format The desired format + * @param[out] string The converted result in string + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c degree or @c format is invalid. + * @see Parse() + */ + static result ToString(double degree, CoordinateFormat format, Tizen::Base::String& string); + + /** + * Converts a string into coordinate degree. + * + * The @c string should be in @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND format. + * + * @since 2.0 + * + * @return An error code + * @param[in] string The string in degree-minute or degree-minute-second representation + * @param[out] degree The converted result in decimal degrees + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c string is not in CoordinateFormat. + * @see ToString() + */ + static result Parse(const Tizen::Base::String& string, double& degree); + + /** + * Copying of objects using this copy assignment operator is allowed. + * + * @since 2.0 + * + * @return A reference to the current instance + * @param[in] rhs An instance of %Coordinates to assign + */ + Coordinates& operator =(const Coordinates& rhs); + +private: + double __latitude; + double __longitude; + double __altitude; + + class _CoordinatesImpl* __pImpl; + friend class _CoordinatesImpl; +}; // Coordinates +}} // Tizen::Locations +#endif // _FLOC_COORDINATES_H_ diff --git a/inc/FLocILocationProviderListener.h b/inc/FLocILocationProviderListener.h new file mode 100644 index 0000000..44b03b9 --- /dev/null +++ b/inc/FLocILocationProviderListener.h @@ -0,0 +1,200 @@ +// +// 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 FLocILocationProviderListener.h +* @brief This is the header file for the %ILocationProviderListener interface. +* +* This header file contains the declarations of the %ILocationProviderListener interface. +*/ + +#ifndef _FLOC_ILOCATION_PROVIDER_LISTENER_H_ +#define _FLOC_ILOCATION_PROVIDER_LISTENER_H_ + +#include <FBaseRtIEventListener.h> +#include <FLocTypes.h> + +namespace Tizen { namespace Locations +{ + +class Location; + +/** +* @interface ILocationProviderListener +* @brief This interface defines listener interfaces to get asynchronous notifications from the location provider. +* +* @since 2.0 +* +* The %ILocationProviderListener interface defines listener interfaces to get asynchronous notifications from the location provider. +* An application should implement this listener interface and construct the location provider with the listener +* to get the asynchronous notifications for the location updates and region monitoring requests. +* +* @see LocationProvider +*/ +class _OSP_EXPORT_ ILocationProviderListener + : virtual public Tizen::Base::Runtime::IEventListener +{ +public: + /** + * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called + * when the destructor of this interface is called. + * + * @since 2.0 + */ + virtual ~ILocationProviderListener(void) {} + + /** + * Called when the location update is running. + * + * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() methods. + * + * Note that, the updated locations may not always fall into the requested accuracy level that the application has specified in the criteria. + * The application is able to filter out less accurate locations by checking the location accuracy with the Location::GetHorizontalAccuracy() method + * if it matters to the application. + * + * During updating locations, along with changes in the location's accuracy, changes in the service status are also notified. + * + * @since 2.0 + * + * @param[in] location The location to update + * @remarks An application should implement this method when it requests for the location updates and wants to handle the updated locations. + * @see OnAccuracyChanged() + * @see OnLocationUpdateStatusChanged() + */ + virtual void OnLocationUpdated(const Tizen::Locations::Location& location) { } + + /** + * Called when the location provider detects a movement entering into the registered region. + * + * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and is identified by the region ID. + * + * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified. + * + * @since 2.0 + * + * @param[in] regionId The ID for the registered region + * @remarks An application should implement this method when it requests for the region monitoring and wants to handle the movement into the region. + * @see OnAccuracyChanged() + * @see OnRegionMonitoringStatusChanged() + */ + virtual void OnRegionEntered(Tizen::Locations::RegionId regionId) { } + + /** + * Called when the location provider detects a movement leaving from the registered region. + * + * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and identified by the region ID. + * + * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified. + * + * @since 2.0 + * + * @param[in] regionId The ID for the registered region + * @remarks An application should implement this method when it requests the region monitoring and wants to handle the movement out of the region. + * @see OnAccuracyChanged() + * @see OnRegionMonitoringStatusChanged() + */ + virtual void OnRegionLeft(Tizen::Locations::RegionId regionId) { } + + /** + * Called when the service status of the location updates change. + * + * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. + * + * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it + * cannot fix the current location due to poor circumstances such as weak radio for positioning. + * When this status continues for a fairly long time, it is recommended to cancel the request. The request should be run after some time in order to avoid excessive battery consumption. + * + * When the user withdraws the permission for an application to use the location information, the status changes to + * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. + * In that case, the application might ask the user to grant permission to continue the aborted service + * or to finalize all resources for the location provider. + * + * The status @c LOC_SVC_STATUS_PAUSED is displayed when the location provider pauses the ongoing service. This happens when the application requests for the location updates without keeping the location updates awake. The status will be changed to others + * once the location provider resumes the paused service. + * + * Note that, the application can get notifications about the location updates and accuracy changes + * only when the service status is @c LOC_SVC_STATUS_RUNNING. + * + * @since 2.0 + * + * @param[in] status The service status of the location updates + * @remarks An application should implement this method when it requests for the location updates and wants to handle status changes of the service. + */ + virtual void OnLocationUpdateStatusChanged(Tizen::Locations::LocationServiceStatus status) { } + + + /** + * Called when the service status of the region monitoring changes. + * + * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. + * + * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it + * cannot fix the location that is suitable for monitoring the regions. + * + * When the user withdraws the permission for an application to use the location information, the status changes to + * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. + * In that case, the application might ask the user to grant permission to continue the aborted service + * or to finalize all resources for the location provider. + * + * Note that, the application can get notifications about the movement around regions and accuracy changes + * only when the service status is @c LOC_SVC_STATUS_RUNNING. + * + * @since 2.0 + * + * @param[in] status The service status of the region monitoring + * @remarks An application should implement this method when it requests for the region monitoring and wants to handle status changes of the service. + */ + virtual void OnRegionMonitoringStatusChanged(Tizen::Locations::LocationServiceStatus status) { } + + + /** + * Called when the accuracy level of the location changes. + * + * The location provider tries to provide accurate location services as specified in the criteria, + * but the location provided by location provider may not always fall into the requested accuracy level. + * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by location provider is changed. + * + * The accuracy changes to @c LOC_ACCURACY_INVALID when the location provider is not running any services in @c LOC_SVC_STATUS_RUNNING + * status. + * + * @since 2.0 + * + * @param[in] accuracy The accuracy of the location + */ + virtual void OnAccuracyChanged(Tizen::Locations::LocationAccuracy accuracy) = 0; + +protected: + // + //This method is for internal use only. Using this method can cause behavioral, security-related, + //and consistency-related issues in the application. + // + virtual void ILocationProviderListener_Reserved1(void) { } + + // + //This method is for internal use only. Using this method can cause behavioral, security-related, + //and consistency-related issues in the application. + // + virtual void ILocationProviderListener_Reserved2(void) { } + + // + //This method is for internal use only. Using this method can cause behavioral, security-related, + //and consistency-related issues in the application. + // + virtual void ILocationProviderListener_Reserved3(void) { } +}; // ILocationProviderListener +}} // Tizen::Locations +#endif // _FLOC_ILOCATION_PROVIDER_LISTENER_H_ diff --git a/inc/FLocLocation.h b/inc/FLocLocation.h new file mode 100644 index 0000000..8163c27 --- /dev/null +++ b/inc/FLocLocation.h @@ -0,0 +1,210 @@ +// +// 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 FLocLocation.h + * @brief This is the header file for the %Location class. + * + * This header file contains the declarations of the %Location class. + */ + +#ifndef _FLOC_LOCATION_H_ +#define _FLOC_LOCATION_H_ + +#include <FBaseObject.h> + +namespace Tizen { namespace Base +{ +class String; +class DateTime; +}} + +namespace Tizen { namespace Locations +{ +class Coordinates; + +/** +* @class Location +* @brief This class contains and provides information about a location including its geographical coordinates, altitude, and so on. +* +* @since 2.0 +* +* @final This class is not intended for extension. +* +* The %Location class contains all information about a location that the location provider fixed at a certain moment. +* It basically provides geographical coordinates and horizontal accuracy that gives the estimated error about the coordinates, +* while the altitude, vertical accuracy, speed, and course at the location are optionally provided. +* It also contains detailed and specific positioning information, such as satellites used to fix the location. +* +* An application obtains the %Location instances from LocationProvider. +*/ +class _OSP_EXPORT_ Location + : public Tizen::Base::Object +{ +public: + /** + * Copying of objects using this copy constructor is allowed. + * + * @since 2.0 + * + * @param[in] rhs An instance of %Location to copy + */ + Location(const Location& rhs); + + /** + * This destructor overrides Tizen::Base::Object::~Object(). + * + * @since 2.0 + */ + virtual ~Location(void); + + /** + * Compares the calling instance with the specified instance for equality. + * + * @since 2.0 + * + * @return @c true if all the fields in the objects are equal, @n + * else @c false + * @param[in] rhs The object to compare + */ + virtual bool Equals(const Tizen::Base::Object& rhs) const; + + /** + * Gets the hash value of the calling instance. + * + * @since 2.0 + * + * @return The hash value of the calling instance + */ + virtual int GetHashCode(void) const; + + /** + * Gets the horizontal accuracy. + * + * @since 2.0 + * + * @return The horizontal accuracy in meters, @n + * else @c NaN if it is not available + */ + double GetHorizontalAccuracy(void) const; + + /** + * Gets the vertical accuracy. + * + * @since 2.0 + * + * @return The vertical accuracy in meters, @n + * else @c NaN if it is not available + */ + double GetVerticalAccuracy(void) const; + + /** + * Gets the course. + * + * The course is the angle of moving direction measured clockwise from true north. + * + * @since 2.0 + * + * @return The course in degrees within the range [0.0, +360.0], @n + * else @c NaN if it is not available + */ + double GetCourse(void) const; + + /** + * Gets the coordinates. + * + * @since 2.0 + * + * @return The geographical coordinates + */ + Coordinates GetCoordinates(void) const; + + /** + * Gets the ground speed. + * + * @since 2.0 + * + * @return The speed in km/h, @n + * else @c NaN if it is not available + */ + double GetSpeed(void) const; + + /** + * Gets the timestamp when this location is fixed. + * + * @since 2.0 + * + * @return The fix time in UTC + */ + Tizen::Base::DateTime GetTimestamp(void) const; + + /** + * Gets the detailed positioning information. + * + * The detailed positioning information is queried using a key, and the %GetExtraInfo() method returns the information corresponding to the key. + * <table> + <tr><th>Key</th><th>Information</th></tr> + <tr><td>location_method</td><td>Positioning technology used to fix this location. Possible values are "gps" and "network".</td></tr> + <tr><td>satellite</td> + <td>GPS satellite information in the semicolon-separated satellite sentences. + Each sentence forms "PRN, Elevation, Azimuth, SNR, Active" where PRN is a satellite ID, Elevation is in degree, Azimuth is in degree, + SNR is a signal to nose ratio in dBHZ, and Active is @c 1, if the satellite is in use for positioning, or @c 0. + For example, it can be "02, 40.0, 83.0, 35.0, 1; 15, 30.0, 65.0, 35.0, 0; 22, 80.0, 120.0, 40.0, 1;".</td> + </tr></table> + * + * @since 2.0 + * + * @return The information corresponding to the key, @n + * else an empty string if the @c key is invalid or the requested information is not available for this location + * @param[in] key The key to the positioning information + */ + Tizen::Base::String GetExtraInfo(const Tizen::Base::String& key) const; + + /** + * Checks the validity for this location. + * + * @since 2.0 + * + * @return @c true if the location is valid, @n + * else @c false + */ + bool IsValid(void) const; + + /** + * Copying of objects using this copy assignment operator is allowed. + * + * @since 2.0 + * + * @return A reference to the current instance + * @param[in] rhs An instance of %Location to assign + */ + Location& operator =(const Location& rhs); + +private: + // + // This default constructor is intentionally declared as private so that only the platform can create an instance. + // + // @since 2.0 + // + Location(void); + +private: + class _LocationImpl* __pImpl; + friend class _LocationImpl; +}; // Location +}} // Tizen::Locations +#endif // _FLOC_LOCATION_H_ diff --git a/inc/FLocLocationCriteria.h b/inc/FLocLocationCriteria.h new file mode 100644 index 0000000..cc62824 --- /dev/null +++ b/inc/FLocLocationCriteria.h @@ -0,0 +1,144 @@ +// +// 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 FLocLocationCriteria.h + * @brief This is the header file for the %LocationCriteria class. + * + * This header file contains the declarations of the %LocationCriteria class. + */ + +#ifndef _FLOC_LOCATION_CRITERIA_H_ +#define _FLOC_LOCATION_CRITERIA_H_ + +#include <FBaseObject.h> +#include <FLocTypes.h> + +namespace Tizen { namespace Locations +{ + +/** +* @class LocationCriteria +* @brief This class provides methods to specify the service quality that an application wants for the location provider. +* +* @since 2.0 +* +* @final This class is not intended for extension. +* +* The %LocationCriteria class provides methods to specify the service quality that an application wants for the location provider. +* The application specifies the location criteria based on its scenario and gives it to the location provider. +* +* The accuracy in the location criteria is for specifying the accuracy levels for the location provider. +* The accuracy @c LOC_ACCURACY_ANY is for getting locations of any accuracy that the location provider provides. +* The application can get more accurate locations as it takes higher accuracy levels from @c LOC_ACCURACY_ONE_KILOMETER, +* @c LOC_ACCURACY_HUNDRED_METERS, @c LOC_ACCURACY_TEN_METERS, and @c LOC_ACCURACY_FINEST. +* The application should be aware that higher accuracy levels makes the location provider run costly positioning systems more. Considering proper +* accuracy levels helps the system to provide efficient services to the user. +* +* @see LocationProvider +*/ +class _OSP_EXPORT_ LocationCriteria + : public Tizen::Base::Object +{ +public: + /** + * Initializes an instance of %LocationCriteria with the accuracy set to @c LOC_ACCURACY_ANY. + * + * @since 2.0 + * @see SetAccuracy() + */ + LocationCriteria(void); + + /** + * This is the copy constructor for the %LocationCriteria class. + * + * Copying of objects using this copy constructor is allowed. + * + * @since 2.0 + * + * @param[in] rhs An instance of %LocationCriteria to copy + */ + LocationCriteria(const LocationCriteria& rhs); + + /** + * This destructor overrides Tizen::Base::Object::~Object(). + * + * @since 2.0 + */ + virtual ~LocationCriteria(void); + + /** + * Compares the calling instance with the specified instance for equality. + * + * @since 2.0 + * + * @return @c true if all the fields in the objects are equal, @n + * else @c false + * @param[in] rhs The object to compare + */ + virtual bool Equals(const Tizen::Base::Object& rhs) const; + + /** + * Gets the hash value of the calling instance. + * + * @since 2.0 + * + * @return The hash value of the calling instance + */ + virtual int GetHashCode(void) const; + + /** + * Sets the desired accuracy. + * + * @since 2.0 + * + * @return An error code + * @param[in] accuracy The desired accuracy + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified @c accuracy is invalid. + * @see GetAccuracy() + */ + result SetAccuracy(LocationAccuracy accuracy); + + /** + * Gets the desired accuracy of this location criteria. + * + * @since 2.0 + * + * @return The accuracy of this location criteria + * @see SetAccuracy() + */ + LocationAccuracy GetAccuracy(void) const; + + /** + * Copying of objects using this copy assignment operator is allowed. + * + * @since 2.0 + * + * @return A reference to the current instance + * @param[in] rhs An instance of %LocationCriteria to assign + */ + LocationCriteria& operator =(const LocationCriteria& rhs); + +private: + LocationAccuracy __accuracy; + + class _LocationCriteriaImpl* __pImpl; + friend class _LocationCriteriaImpl; +}; // LocationCriteria +}} // Tizen::Locations +#endif // _FLOC_LOCATION_CRITERIA_H_ diff --git a/inc/FLocLocationProvider.h b/inc/FLocLocationProvider.h new file mode 100755 index 0000000..33a6c60 --- /dev/null +++ b/inc/FLocLocationProvider.h @@ -0,0 +1,359 @@ +// +// 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_ diff --git a/inc/FLocTypes.h b/inc/FLocTypes.h new file mode 100644 index 0000000..e24341f --- /dev/null +++ b/inc/FLocTypes.h @@ -0,0 +1,83 @@ +// +// 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 FLocTypes.h +* @brief This is the header file for the types and constants in the Locations namespace. +* +* This header file contains the declarations for the types and constants in the Locations namespace. +*/ + +#ifndef _FLOC_TYPES_H_ +#define _FLOC_TYPES_H_ + +namespace Tizen { namespace Locations +{ +/** +* A region ID that identifies a monitoring region registered to LocationProvider. +* +* @since 2.0 +*/ +typedef int RegionId; + +/** +* @enum CoordinateFormat +* +* Defines the format for angle representation in degrees, minutes, and seconds. +* +* @since 2.0 +*/ +enum CoordinateFormat +{ + COORDINATE_FORMAT_DEGREE_MINUTE = 0, /**< The "DD:MM.mm" format, where DD is degrees, MM is minutes, and mm is decimal fraction of a minute */ + COORDINATE_FORMAT_DEGREE_MINUTE_SECOND, /**< The "DD:MM:SS.ss" format, where DD is degrees, MM is minutes, SS is seconds, and ss is decimal fraction of a second */ +}; + +/** +* @enum LocationAccuracy +* +* Defines the accuracy of the location. +* +* @since 2.0 +*/ +enum LocationAccuracy +{ + LOC_ACCURACY_INVALID = 0, /**< Invalid accuracy @n The location provider uses this value when the location is not available. */ + LOC_ACCURACY_FINEST, /**< The accuracy of the location is the finest that the location provider provides */ + LOC_ACCURACY_TEN_METERS, /**< The accuracy of the location is under 10 meters */ + LOC_ACCURACY_HUNDRED_METERS, /**< The accuracy of the location is under 100 meters */ + LOC_ACCURACY_ONE_KILOMETER, /**< The accuracy of the location is under 1 kilometer */ + LOC_ACCURACY_ANY, /**< The accuracy of the location can be anything that the location provider provides */ +}; + +/** +* @enum LocationServiceStatus +* +* Defines the location service status that the location provider provides. +* +* @since 2.0 +*/ +enum LocationServiceStatus +{ + LOC_SVC_STATUS_IDLE = 0, /**< The status of the location service is idle */ + LOC_SVC_STATUS_RUNNING, /**< The location provider is successfully running the requested service */ + LOC_SVC_STATUS_PAUSED, /**< The location provider has paused the location service */ + LOC_SVC_STATUS_DENIED, /**< The location provider is unable to provide services because the user restricted the use of location service */ + LOC_SVC_STATUS_NOT_FIXED, /**< The location provider is trying to run the service by fixing the current location */ +}; +}} // Tizen::Locations +#endif // _FLOC_TYPES_H_ diff --git a/inc/FLocations.h b/inc/FLocations.h new file mode 100644 index 0000000..858d2fc --- /dev/null +++ b/inc/FLocations.h @@ -0,0 +1,56 @@ +// +// 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 FLocations.h + * @brief This is the header file for the %Locations namespace. + * + * This header file contains the declarations and descriptions of the %Locations namespace. + * + */ +#ifndef _FLOCATIONS_H_ +#define _FLOCATIONS_H_ + +// Includes +#include "FLocCoordinates.h" +#include "FLocILocationProviderListener.h" +#include "FLocLocation.h" +#include "FLocLocationCriteria.h" +#include "FLocLocationProvider.h" +#include "FLocTypes.h" + +/** + * @namespace Tizen::Locations + * @brief This namespace contains the classes and interfaces for the location-related information and services. + * @since 2.0 + * + * @remarks @b Header @b %file: @b \#include @b <FLocations.h> @n + * @b Library : @b osp-locations + * + * The %Locations namespace contains the classes and interfaces for the location-related information and services. + * + * For more information on the %Locations namespace features, see <a href="../org.tizen.native.appprogramming/html/guide/locations/locations_namespace.htm">Locations Guide</a>. + * + * The following diagram illustrates the relationships between the classes belonging to the %Locations namespace. + * @image html locations_namespace_classdiagram.png + */ + +namespace Tizen { namespace Locations +{ +}} // Tizen::Locations + +#endif // _FLOCATIONS_H_ |