*
* @final This class is not intended for extension.
*
-* The %Coordinates class represents a geographical point specified by latitude, longitude, and altitude values and provides
+* The %Coordinates class represents a geographical point specified by its latitude, longitude, and altitude values and provides the
* 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.
+* The latitude and longitude in decimal degrees are sometimes represented in the degrees, minutes, and seconds format. For example, 40.1874 degrees
+* can also be represented as "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.
*/
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. @n
+ /**
+ * Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number. @n
* 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
*/
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.
+ /**
+ * Compares the specified instance with the current 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
+ * @return @c true if all the fields in the objects are equal, @n
+ * else @c false
+ * @param[in] rhs The object to compare with the current instance
*/
virtual bool Equals(const Tizen::Base::Object& rhs) const;
- /**
- * Gets the hash value of the calling instance.
+ /**
+ * Gets the hash value of the current instance.
*
* @since 2.0
*
- * @return The hash value of the calling instance
+ * @return The hash value of the current instance
*/
virtual int GetHashCode(void) const;
- /**
+ /**
* Sets the latitude, longitude, and altitude values of the coordinates. @n
- * An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. @n
- * Otherwise, the %Set() method returns an @c E_INVALID_ARG exception.
+ * An application should specify the latitude and longitude values within the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. @n
+ * Otherwise, the %Set() method returns @c E_INVALID_ARG.
*
- * @since 2.0
+ * @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.
+ * @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 Either the specified @c latitude or the specified @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. @n
- * An application should specify latitude value in the valid range of [-90.0, +90.0]. @n
- * Otherwise, the %SetLatitude() method returns an @c E_INVALID_ARG exception.
+ * An application should specify the latitude value within the valid range of [-90.0, +90.0]. @n
+ * Otherwise, the %SetLatitude() method returns @c E_INVALID_ARG.
*
* @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.
+ * @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. @n
- * An application should specify longitude value in the valid range of [-180.0, +180.0]. @n
- * Otherwise, the %SetLongitude() method returns an @c E_INVALID_ARG exception.
+ * An application should specify the longitude value within the valid range of [-180.0, +180.0]. @n
+ * Otherwise, the %SetLongitude() method returns @c E_INVALID_ARG.
*
* @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.
+ * @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()
+ * @see GetAltitude()
*/
void SetAltitude(double altitude);
- /**
+ /**
* Gets the latitude value of the coordinates.
*
* @since 2.0
*/
double GetLatitude(void) const;
- /**
+ /**
* Gets the longitude value of the coordinates.
*
* @since 2.0
*/
double GetLongitude(void) const;
- /**
+ /**
* Gets the altitude value of the coordinates.
*
* @since 2.0
*/
double GetAltitude(void) const;
- /**
+ /**
* Calculates the azimuth value. @n
* The coordinates are the starting point and @c dest is the destination for the azimuth calculation. @n
* The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model. @n
- * The altitude value is not considered in calculation.
+ * The altitude value is not considered in the 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
+ * @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 the two points has a @c NaN value
+ * @param[in] dest The destination coordinates
*/
double GetAzimuth(const Coordinates& dest) const;
- /**
+ /**
* Calculates the geodetic distance for the given coordinates. @n
* The distance calculation is based on the WGS84 ellipsoid model. @n
- * The altitude value is not considered in calculation.
+ * The altitude value is not considered in the calculation.
*
* @since 2.0
*
- * @return The distance for 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
+ * @return The distance for the given coordinates in meters, @n
+ * else @c NaN if the latitude or the longitude of the two points has a @c NaN value
+ * @param[in] to The destination coordinates
*/
double GetDistanceTo(const Coordinates& to) const;
- /**
- * Converts the coordinate value into string. @n
- * An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the result string.
+ /**
+ * Converts the coordinate value into a string. @n
+ * An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the resultant 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.
+ * @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 as a string
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_ARG Either the specified @c degree or the specified @c format is invalid.
* @see Parse()
*/
static result ToString(double degree, CoordinateFormat format, Tizen::Base::String& string);
- /**
- * Converts a string into coordinate degree. @n
- * The @c string should be in @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND format.
+ /**
+ * Converts a string into the coordinate degree. @n
+ * The @c string should be in the ::COORDINATE_FORMAT_DEGREE_MINUTE or ::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()
+ * @return An error code
+ * @param[in] string The string in the 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 the coordinate format.
+ * @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
+ * @return A reference to the current instance
* @param[in] rhs An instance of %Coordinates to assign
*/
Coordinates& operator =(const Coordinates& rhs);
//
/**
-* @file FLocILocationProviderListener.h
-* @brief This is the header file for the %ILocationProviderListener interface.
-*
-* This header file contains the declarations of the %ILocationProviderListener interface.
-*/
+ * @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_
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
-*/
+ * @interface ILocationProviderListener
+ * @brief This interface is a listener interface to get asynchronous notifications from the location provider.
+ *
+ * @since 2.0
+ *
+ * The %ILocationProviderListener interface is a listener interface 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 asynchronous notifications for 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. @n This way, the destructors of the derived classes are called
- * when the destructor of this interface is called.
+ /**
+ * This polymorphic destructor should be overridden if required. @n
+ * 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. @n
- * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() methods. @n
+ * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() method. @n
* Note that, the updated locations may not always fall into the requested accuracy level that the application has specified in the criteria. @n
- * The application is able to filter out less accurate locations by checking the location accuracy with the Location::GetHorizontalAccuracy() method
+ * The application can filter out less accurate locations by checking the location accuracy with the Location::GetHorizontalAccuracy() method,
* if it matters to the application. @n
- * During updating locations, along with changes in the location's accuracy, changes in the service status are also notified.
+ * While 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()
+ * @remarks An application should implement this method when it requests for 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. @n
- * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and is identified by the region ID. @n
- * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified.
+ * A region is registered for monitoring by calling the LocationProvider::AddMonitoringRegion() method and is identified by the region ID. @n
+ * While monitoring regions, along with changes in the location's accuracy, changes in the service status are also 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.
+ * @param[in] regionId The ID of the registered region
+ * @remarks An application should implement this method when it requests for region monitoring and wants to handle the movement entering 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. @n
- * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and identified by the region ID. @n
- * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified.
+ /**
+ * Called when the location provider detects a movement leaving the registered region. @n
+ * A region is registered for monitoring by calling the LocationProvider::AddMonitoringRegion() method and is identified by the region ID. @n
+ * While monitoring regions, along with changes in the location's accuracy, changes in the service status are also 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.
+ * @remarks An application should implement this method when it requests for 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. @n
+ /**
+ * Called when the service status of the location updates changes. @n
* The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. @n
* 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. @n
* @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. @n
* 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. @n
- * 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
+ * The status @c LOC_SVC_STATUS_PAUSED is displayed when the location provider pauses the ongoing service. This happens when the application requests for location updates without keeping the location updates awake. The status is changed to others
* once the location provider resumes the paused service. @n
- * Note that, the application can get notifications about the location updates and accuracy changes
+ * Note that, the application can get notifications about 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.
+ * @remarks An application should implement this method when it requests for 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. @n
* The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service. @n
* The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it
* @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application. @n
* 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. @n
- * Note that, the application can get notifications about the movement around regions and accuracy changes
+ * Note that, the application can get notifications about the movement around regions and the 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.
+ * @remarks An application should implement this method when it requests for region monitoring and wants to handle the status changes of the service.
*/
virtual void OnRegionMonitoringStatusChanged(Tizen::Locations::LocationServiceStatus status) { }
- /**
+ /**
* Called when the accuracy level of the location changes. @n
* 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. @n
- * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by location provider is changed. @n
- * The accuracy changes to @c LOC_ACCURACY_INVALID when the location provider is not running any services in @c LOC_SVC_STATUS_RUNNING
+ * but the location provided by the location provider may not always fall into the requested accuracy level. @n
+ * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by the location provider is changed. @n
+ * The accuracy changes to @c LOC_ACCURACY_INVALID when the location provider is not running any services in the @c LOC_SVC_STATUS_RUNNING
* status.
*
* @since 2.0
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.
- //
+ //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.
- //
+ //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.
- //
+ //Using this method can cause behavioral, security-related and consistency-related issues in the application.
virtual void ILocationProviderListener_Reserved3(void) { }
}; // ILocationProviderListener
}} // Tizen::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 Location
+ * @brief This class 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 information about a location fixed by the location provider at a certain moment.
+ * It basically provides the geographical coordinates and horizontal accuracy that determines the estimated error of 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 the 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
*/
Location(const Location& rhs);
- /**
- * This destructor overrides Tizen::Base::Object::~Object().
- *
- * @since 2.0
- */
+ /**
+ * This destructor overrides Tizen::Base::Object::~Object().
+ *
+ * @since 2.0
+ */
virtual ~Location(void);
- /**
- * Compares the calling instance with the specified instance for equality.
+ /**
+ * Compares the specified instance with the current 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
+ * @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.
+ /**
+ * Gets the hash value of the current instance.
*
* @since 2.0
*
- * @return The hash value of the calling instance
+ * @return The hash value of the current instance
*/
virtual int GetHashCode(void) const;
- /**
+ /**
* Gets the horizontal accuracy.
*
* @since 2.0
*/
double GetHorizontalAccuracy(void) const;
- /**
+ /**
* Gets the vertical accuracy.
*
* @since 2.0
*/
double GetVerticalAccuracy(void) const;
- /**
+ /**
* Gets the course.
*
- * The course is the angle of moving direction measured clockwise from true north.
+ * The course is the angle of the moving direction measured clockwise from true north.
*
* @since 2.0
*
*/
double GetCourse(void) const;
- /**
+ /**
* Gets the coordinates.
*
* @since 2.0
*/
Coordinates GetCoordinates(void) const;
- /**
+ /**
* Gets the ground speed.
*
* @since 2.0
*/
double GetSpeed(void) const;
- /**
+ /**
* Gets the timestamp when this location is fixed.
*
* @since 2.0
*/
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.
<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.
+ Each sentence forms "PRN, Elevation, Azimuth, SNR, Active" where PRN is a satellite ID, Elevation is in degrees, Azimuth is in degrees,
+ SNR is the signal to nose ratio in dBHZ, and Active is @c 1, if the satellite is being used 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
+ * @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.
+ /**
+ * Checks the validity of this location.
*
* @since 2.0
*
*/
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
+ * @return A reference to the current instance
+ * @param[in] rhs An instance of %Location to assign
*/
Location& operator =(const Location& rhs);
{
/**
-* @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 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 the 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 if it specifies higher accuracy levels such as @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 make the location provider run costly positioning systems more often. Considering proper
+ * accuracy levels helps the system 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
*/
LocationCriteria(void);
- /**
+ /**
* This is the copy constructor for the %LocationCriteria class. @n
* Copying of objects using this copy constructor is allowed.
*
*/
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.
+ /**
+ * Compares the specified instance with the current 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
+ * @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.
+ /**
+ * Gets the hash value of the current instance.
*
* @since 2.0
*
- * @return The hash value of the calling instance
+ * @return The hash value of the current 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.
+ * @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
*/
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
+ * @return A reference to the current instance
+ * @param[in] rhs An instance of %LocationCriteria to assign
*/
LocationCriteria& operator =(const LocationCriteria& rhs);
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 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, such as location providing and region monitoring.
+ * The location provider is constructed with a location criteria and offers services to satisfy it in a best-effort manner.
+ * An application gets locations by simply calling the GetLocation() method, or by requesting asynchronous location updates using 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 service by assigning a listener, which implements the %ILocationProviderListener interface, for 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. @n
* For full construction, the Construct() method must be called right after
* calling this constructor.
*/
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. @n
- * 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. @n
- * The location provider tries to provides locations and services based on the specified @c criteria. @n
- * The @c listener is notified on asynchronous location updates or region monitoring events.
+ * An application chooses the desired service quality based on the scenario and constructs the location provider with the specified
+ * @c criteria. The desired accuracy for the location provision is a configurable property of LocationCriteria. @n
+ * The location provider tries to provide locations and services based on the specified @c criteria. @n
+ * The @c listener is notified about asynchronous location updates or region monitoring events.
*
* @since 2.0
*
- * @feature %http://tizen.org/feature/location
- * @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.
+ * @feature %http://tizen.org/feature/location
+ * @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.
* @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
- * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
+ *
For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
* @remarks Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
*/
result Construct(const LocationCriteria& criteria, ILocationProviderListener& listener);
- /**
- * Requests the location updates service with the specific @c interval. @n
+ /**
+ * Requests the location updates service with the specified @c interval. @n
* 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. @n
- * 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. @n The location provider notifies the listener whenever the accuracy
+ * The location provider tries to provide accurate locations as requested in the criteria, but locations that are updated by the location provider
+ * do not always fall into the requested accuracy level. It provides locations with low-grade accuracy if that is all it can offer
+ * or does not even provide locations if it has hardly fixed the current location. @n The location provider notifies the listener whenever the accuracy
* level of ongoing updates are changed by calling the ILocationProviderListener::OnAccuracyChanged() method. @n
- * 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. @n This is possible for the following situations:
- * - The application is not running in foreground.
+ * The location updates can be paused by the location provider when the application is unable to point out locations to the user
+ * at the moment. @n This is possible in the following situations:
+ * - The application is not running in the foreground.
* - The screen is off.
*
* In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. @n
- * It resumes the paused location updates when the application gets out of the situations. @n
- * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n
- * The change in the service status that the location provider is providing are notified to the listener
+ * It resumes the paused location updates when the application gets out of the situation. @n
+ * To get location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n
+ * The change in the service status provided by the location provider is notified to the listener
* by calling the ILocationProviderListener::OnLocationUpdateStatusChanged() method. @n
- * 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.
+ * If location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() method,
+ * the location provider cancels the previous request and restarts the updates with the specified parameter.
*
- * @since 2.0
+ * @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location
+ * @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.
+ * @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 has blocked the application from using the location information.
* @see StopLocationUpdates()
*/
result StartLocationUpdatesByInterval(int interval);
- /**
- * Requests the location updates service with the specific @c distance filter. @n
+ /**
+ * Requests the location updates service with the specified @c distance filter. @n
* 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. @n Then the location provider updates subsequent locations
- * when it changes over the specified @c distance. @n
- * 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. @n This is possible for the following situations:
- * - The application is not running in foreground.
+ * as they change over the specified @c distance. @n
+ * The location updates can be paused by the location provider when the application is unable to point out locations to the user
+ * at the moment. @n This is possible in the following situations:
+ * - The application is not running in the foreground.
* - The screen is off.
*
* In this case, the location provider notifies the status @c LOC_SVC_STATUS_PAUSED to the listener. @n
- * It resumes the paused location updates when the application gets out of the situations. @n
- * To get the location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n
+ * It resumes the paused location updates when the application gets out of the situation. @n
+ * To get location updates all the time, the application should use the KeepLocationUpdateAwake() method. @n
* 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()
+ * is notified to the listener when changes occur by calling the ILocationProviderListener::OnLocationUpdateStatusChanged()
* and ILocationProviderListener::OnAccuracyChanged() methods respectively. @n
- * 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.
+ * If the location updates are already started by calling the StartLocationUpdatesByInterval() or StartLocationUpdatesByDistance() method,
+ * the location provider cancels the previous request and restarts the updates with the specified parameter.
*
* @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location
+ * @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.
+ * @return An error code
+ * @param[in] distance The distance in meters
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The specified @c distance is less than or equal to @c 0.0.
+ * - The specified @c distance 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 has blocked the 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.
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_OPERATION The location updates have not been requested.
* @see StartLocationUpdatesByInterval()
* @see StartLocationUpdatesByDistance()
*/
result StopLocationUpdates(void);
- /**
- * Keeps the location updates awake or not. @n
- * The location provider can pause the ongoing location updates when the application is unable to point locations out to the user
- * for the moment. @n This is possible for the following situations:
- * - The application is not running in foreground.
+ /**
+ * Keeps the location updates awake. @n
+ * The location provider can pause the ongoing location updates when the application is unable to point out locations to the user
+ * at the moment. @n This is possible in the following situations:
+ * - The application is not running in the 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. @n
- * The application should be cautious about doing so since it can make the system awake
- * during the location updates.
+ * To get location updates all the time, the application should use the StartLocationUpdatesByInterval() or
+ * StartLocationUpdatesByDistance() method along with the %KeepLocationUpdateAwake() method turning the flag @c enable on. @n
+ * The application should be cautious while doing so as it can make the system awake
+ * during location updates.
*
* @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
- * Both privileges are required.
+ * @privilege %http://tizen.org/privilege/location and
+ * %http://tizen.org/privilege/power @n
+ * Both the 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.
- * @exception E_USER_NOT_CONSENTED The user blocks an application from using the location information. @b Since: @b 2.1
+ * @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.
+ * @exception E_USER_NOT_CONSENTED The user has blocked the application from using the location information. @b Since: @b 2.1
* @see StartLocationUpdatesByInterval()
* @see StartLocationUpdatesByDistance()
* @see StopLocationUpdates()
*/
result KeepLocationUpdateAwake(bool enable);
- /**
+ /**
* Adds a region for monitoring. @n
* A region is defined by a center point and a radius. @n
- * 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. @n
+ * The location provider starts the region monitoring service until all the regions are removed. When it detects a movement that crosses the
+ * boundary of a registered region, it notifies the application by calling the ILocationProviderListener::OnRegionEntered() or
+ * ILocationProviderListener::OnRegionLeft() method with the region identifier that is returned by the %AddMonitoringRegion() method. @n
* The altitude of @c regionCenter is not considered in monitoring. @n
* 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()
+ * is notified to the listener when changes occur by calling the ILocationProviderListener::OnRegionMonitoringStatusChanged()
* and ILocationProviderListener::OnAccuracyChanged() methods respectively. @n
* Note that, the monitoring service can sometimes makes the system awake by running costly positioning devices.
*
* @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location and %http://tizen.org/privilege/power @n
- * Both privileges are required.
+ * @privilege %http://tizen.org/privilege/location and
+ * %http://tizen.org/privilege/power @n
+ * Both the 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 radius 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.
+ * @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 Either of the following conditions has occurred:
+ * - The @c radius is not within the supported monitoring radius range, which is currently [50, 100000] meters,
+ * - Either the @c radius, latitude, or 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 has blocked the 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.
+ * @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.
+ /**
+ * Removes all the regions that the location provider monitors.
*
* @since 2.0
*
*/
void RemoveAllMonitoringRegions(void);
- /**
+ /**
* Gets the current service status of the location updates. @n
* 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. @n
- * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnLocationUpdateStatusChanged() listener method.
+ * Otherwise, it returns the service status last notified 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. @n
* The region monitoring service is started by calling the AddMonitoringRegion() method. @n
* If an application has not made valid requests for the service, the %GetRegionMonitoringStatus() method returns @c LOC_SVC_STATUS_IDLE. @n
- * Otherwise, it returns the service status notified last by the ILocationProviderListener::OnRegionMonitoringStatusChanged() listener method.
+ * Otherwise, it returns the service status last notified 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. @n
+ /**
+ * Gets the accuracy level that is currently provided by the location provider. @n
* If an application has not made valid requests for location updates and region monitoring, the %GetCurrentAccuracy() method
* returns @c LOC_ACCURACY_INVALID. @n
* Otherwise, it returns the accuracy level last notified by the ILocationProviderListener::OnAccuracyChanged() listener method.
*/
LocationAccuracy GetCurrentAccuracy(void) const;
- /**
- * Gets a current location. @n
- * An application can simply get the current location with the %GetLocation() method. @n
- * The location provider runs and waits for positioning systems to fix the current location as requested in the criteria. @n
- * If it is not fixed in some time, this method call is aborted and returns a location in low-grade accuracy or even
+ /**
+ * Gets the current location. @n
+ * An application can simply get the current location using the %GetLocation() method. @n
+ * The location provider runs and waits for the positioning system to fix the current location as requested in the criteria. @n
+ * If it is not fixed in some time, this method call is aborted and it returns a location with low-grade accuracy, else it returns
* an invalid location with an @c E_LOCATION_UNAVAILABLE error.
*
* @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location
+ * @privilege %http://tizen.org/privilege/location
*
- * @feature %http://tizen.org/feature/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_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
+ * @feature %http://tizen.org/feature/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 has failed to fix the current location.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
+ * @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
* For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
- * @exception E_USER_NOT_CONSENTED The user blocks an application from using the location information.
- * @exception E_SYSTEM A system error has occurred.
+ * @exception E_USER_NOT_CONSENTED The user has blocked the 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.
+ * - This method call takes time as the location provider runs and waits for the positioning system.
* - The specific error code can be accessed using the GetLastResult() method.
* - Before calling this method, check whether the feature is supported by
* Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
*/
static Location GetLocation(const LocationCriteria& criteria);
- /**
+ /**
* Gets the last known location. @n
- * The %GetLastKnownLocation() method returns the last location the system keeps. @n
- * 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.
+ * The %GetLastKnownLocation() method returns the last location present in the system. @n
+ * It is always a good idea to prefer using this method than requesting current locations,
+ * as using the last location prevents the location provider from running costly positioning systems.
*
* @since 2.0
* @privlevel public
- * @privilege %http://tizen.org/privilege/location
+ * @privilege %http://tizen.org/privilege/location
*
- * @feature %http://tizen.org/feature/location
- * @return The last location
- * @exception E_SUCCESS The method is successful.
+ * @feature %http://tizen.org/feature/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_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
+ * @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
* For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
- * @exception E_USER_NOT_CONSENTED The user blocks an application from using the location information.
+ * @exception E_USER_NOT_CONSENTED The user has blocked the application from using the location information.
* @remarks
* - The specific error code can be accessed using the GetLastResult() method.
* - Before calling this method, check whether the feature is supported by
//
/**
-* @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.
-*/
+ * @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
-*/
+ * 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
+ *
+ * Defines the format for the 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 */
+ COORDINATE_FORMAT_DEGREE_MINUTE = 0, /**< The "DD:MM.mm" format, where DD is degrees, MM is minutes, and mm is the 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 the decimal fraction of a second */
};
/**
-* @enum LocationAccuracy
-*
-* Defines the accuracy of the location.
-*
-* @since 2.0
-*/
+ * @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_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 possible value 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 */
+ 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
+ *
+ * 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 */
+ 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 has restricted the use of the 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_
/**
* @namespace Tizen::Locations
- * @brief This namespace contains the classes and interfaces for the location-related information and services.
+ * @brief This namespace contains classes and interfaces for location-related information and services.
* @since 2.0
*
* @remarks @b Header @b %file: @b \#include @b <FLocations.h> @n
- * @b Library : @b osp-locations
+ * @b Library: @b osp-locations
*
- * The %Locations namespace contains the classes and interfaces for the location-related information and services.
+ * The %Locations namespace contains classes and interfaces for 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>.
*
-version: 1.2.2.1
-Author: Nandan S R (nandan.sr@samsung.com)
-Change: 1) In region Monitoring, use the core accuracy value, instead of LocationAccuracy enum. 2) During WPS positioning, when accuracy is not met by WPS and GPS is not available, the timer value changed to 10 sec if the requested accuracy is FINEST or TEN_METERS.
++[Version] osp-locations_1.2.2.3
++[Date] 10 Sep 2013
++[Title] Fix the problem where thread is blocked when error happens in OnStart
++[Issue#] P130901-00780
++[Problem] In Low battery case when navigation application is opened, crash occurs.
++[Cause] The thread is blocked when there is some problem in the OnStart as Monitor notify is not called.
++[Solution] Change SysTryReturn to SysTryCatch and handle the notify in Catch block.
++[Developer] Nandan SR (nandan.sr@samsung.com)
++==============================================================================
++[Version] osp-locations_1.2.2.2
++[Date] 05 Sep 2013
++[Title] Change the spec file related to secure logs
++[Issue#] N/A
++[Problem] N/A
++[Cause] N/A
++[Solution] Change the spec file
++[Developer] Nandan SR (nandan.sr@samsung.com)
++==============================================================================
++[Version] osp-locations_1.2.2.1
++[Date] 01 July 2014
++[Title] 1) In region Monitoring, use the core accuracy value, instead of LocationAccuracy enum. 2) During WPS positioning, when accuracy is not met by WPS and GPS is not available, the timer value changed to 10 sec if the requested accuracy is FINEST or TEN_METERS.
++[Issue#] N/A
++[Problem] Performance
++[Cause] Non usage of raw values
++[Solution] Use raw values and proper time out
++[Developer] Nandan SR (nandan.sr@samsung.com)
+===============================================================================
+%define debug_package %{nil}
%define __strip /bin/true
Name: osp-locations
Summary: The Locations library of OSP
-Version: 1.2.2.1
+Version: 1.2.2.3
Release: 2
Group: System/Libraries
License: Apache License, Version 2
%setup -q
%build
+%if 0%{?tizen_build_binary_release_type_eng}
+CXXFLAGS="$CXXFLAGS -D_SECURE_LOG"
+%endif
MAJORVER=`echo %{version} | awk 'BEGIN {FS="."}{print $1}'`
%ifarch %{ix86}
-CXXFLAGS="$CXXFLAGS -D_OSP_DEBUG_ -D_SECURE_LOG -D_OSP_X86_ -D_OSP_EMUL_" cmake . -DCMAKE_INSTALL_PREFIX=%{_prefix} -DOBS=1 -DFULLVER=%{version} -DMAJORVER=${MAJORVER} -DARCH=x86
+%if 0%{?simulator}
+CXXFLAGS="$CXXFLAGS -D_OSP_DEBUG_ -D_OSP_X86_ -D_OSP_EMUL_" cmake . -DCMAKE_INSTALL_PREFIX=%{_prefix} -DOBS=1 -DFULLVER=%{version} -DMAJORVER=${MAJORVER} -DARCH=x86
+%else
+CXXFLAGS="$CXXFLAGS -D_OSP_DEBUG_ -D_OSP_X86_ " cmake . -DCMAKE_INSTALL_PREFIX=%{_prefix} -DOBS=1 -DFULLVER=%{version} -DMAJORVER=${MAJORVER} -DARCH=x86
+%endif
%else
+
+%if 0%{?tizen_build_binary_release_type_eng}
CXXFLAGS="-O2 -g -pipe -Wall -fno-exceptions -Wformat -Wformat-security -Wl,--as-needed -fmessage-length=0 -march=armv7-a -mtune=cortex-a8 -mlittle-endian -mfpu=neon -mfloat-abi=softfp -D__SOFTFP__ -mthumb -Wa,-mimplicit-it=thumb -funwind-tables -D_OSP_DEBUG_ -D_SECURE_LOG -D_OSP_ARMEL_" cmake . -DCMAKE_INSTALL_PREFIX=%{_prefix} -DOBS=1 -DFULLVER=%{version} -DMAJORVER=${MAJORVER} -DARCH=arm
+%else
+CXXFLAGS="-O2 -g -pipe -Wall -fno-exceptions -Wformat -Wformat-security -Wl,--as-needed -fmessage-length=0 -march=armv7-a -mtune=cortex-a8 -mlittle-endian -mfpu=neon -mfloat-abi=softfp -D__SOFTFP__ -mthumb -Wa,-mimplicit-it=thumb -funwind-tables -D_OSP_DEBUG_ -D_OSP_ARMEL_" cmake . -DCMAKE_INSTALL_PREFIX=%{_prefix} -DOBS=1 -DFULLVER=%{version} -DMAJORVER=${MAJORVER} -DARCH=arm
+%endif
+
%endif
# Call make instruction with smp support
bool
_LocationManager::OnStart(void)
{
+ SysLog(NID_LOC, "Location manager OnStart is called.");
SysTryReturn(NID_LOC, __pInitMonitor, false, E_INVALID_STATE, "[E_INVALID_STATE] __pInitMonitor must not be null.");
int res = -1;
+ result r = E_SUCCESS;
std::unique_ptr< ArrayList, AllElementsDeleter > pLocInfoRequestList(new (std::nothrow) ArrayList(SingleObjectDeleter));
- SysTryReturn(NID_LOC, pLocInfoRequestList != null, false, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
- result r = pLocInfoRequestList->Construct();
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the Location Request list.");
-
std::unique_ptr< ArrayList, AllElementsDeleter > pSyncLocInfoRequestList(new (std::nothrow) ArrayList(SingleObjectDeleter));
- SysTryReturn(NID_LOC, pSyncLocInfoRequestList != null, false, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ std::unique_ptr< ArrayList, AllElementsDeleter > pAlarmInfoRequestList(new (std::nothrow) ArrayList(SingleObjectDeleter));
+ std::unique_ptr< Tizen::Locations::Location > pGpsLocation(_LocationImpl::GetLocationInstanceN());
+ std::unique_ptr< Tizen::Locations::Location > pWpsLocation(_LocationImpl::GetLocationInstanceN());
+ std::unique_ptr< Timer > pLocUpdateTimer(new (std::nothrow) Timer());
+ std::unique_ptr< Timer > pLocCheckTimer(new (std::nothrow) Timer());
+ std::unique_ptr< Timer > pLocMgrSubstateTimer(new (std::nothrow) Timer());
+
+ r = SettingInfo::AddSettingEventListener(*this);
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to set the setting event listener.");
+
+ SysTryCatch(NID_LOC, pLocInfoRequestList != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ r = pLocInfoRequestList->Construct();
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the Location Request list.");
+
+ SysTryCatch(NID_LOC, pSyncLocInfoRequestList != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
r = pSyncLocInfoRequestList->Construct();
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the Sync Location Request list.");
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the Sync Location Request list.");
- std::unique_ptr< ArrayList, AllElementsDeleter > pAlarmInfoRequestList(new (std::nothrow) ArrayList(SingleObjectDeleter));
- SysTryReturn(NID_LOC, pAlarmInfoRequestList != null, false, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ SysTryCatch(NID_LOC, pAlarmInfoRequestList != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
r = pAlarmInfoRequestList->Construct();
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the Sync Location Request list.");
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the Sync Location Request list.");
- unique_ptr< Tizen::Locations::Location > pGpsLocation(_LocationImpl::GetLocationInstanceN());
- SysTryReturn(NID_LOC, pGpsLocation != null, false, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
- unique_ptr< Tizen::Locations::Location > pWpsLocation(_LocationImpl::GetLocationInstanceN());
- SysTryReturn(NID_LOC, pWpsLocation != null, false, E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ SysTryCatch(NID_LOC, pGpsLocation != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ SysTryCatch(NID_LOC, pWpsLocation != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+
+ SysTryCatch(NID_LOC, pLocUpdateTimer != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ SysTryCatch(NID_LOC, pLocCheckTimer != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
+ SysTryCatch(NID_LOC, pLocMgrSubstateTimer != null, , E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
- std::unique_ptr< Timer > pLocUpdateTimer(new (std::nothrow) Timer());
r = pLocUpdateTimer->Construct(*this);
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the location update timer.");
- std::unique_ptr< Timer > pLocCheckTimer(new (std::nothrow) Timer());
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the location update timer.");
+
r = pLocCheckTimer->Construct(*this);
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the location chek timer.");
- std::unique_ptr< Timer > pLocMgrSubstateTimer(new (std::nothrow) Timer());
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the location chek timer.");
+
r = pLocMgrSubstateTimer->Construct(*this);
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to construct the location manager sub state timer.");
+ SysTryCatch(NID_LOC, r == E_SUCCESS, , E_SYSTEM, "[E_SYSTEM] Failed to construct the location manager sub state timer.");
- r = SettingInfo::AddSettingEventListener(*this);
- SysTryReturn(NID_LOC, r == E_SUCCESS, false, E_SYSTEM, "[E_SYSTEM] Failed to set the setting event listener.");
+ SysLog(NID_LOC, "Now the core Location Managers will be created.");
res = location_manager_create(LOCATIONS_METHOD_GPS, &__locMgrStatus.gpsHandler.handle);
SysTryCatch(NID_LOC, res == 0, , E_SYSTEM, "[E_SYSTEM] Failed to create Native GPS Location provider.");
res = location_manager_set_service_state_changed_cb(__locMgrStatus.gpsHandler.handle, GpsServiceUpdateCallback, this);
SysTryCatch(NID_LOC, res == 0, , E_SYSTEM, "[E_SYSTEM] Failed to register service callback for Native GPS Location provider.");
+ SysLog(NID_LOC, "Core Location Managers created successfully.");
res = location_manager_create(LOCATIONS_METHOD_WPS, &__locMgrStatus.wpsHandler.handle);
SysTryCatch(NID_LOC, res == 0, , E_SYSTEM, "[E_SYSTEM] Failed to create Native WPS Location provider.");
res = location_manager_set_service_state_changed_cb(__locMgrStatus.wpsHandler.handle, WpsServiceUpdateCallback, this);
}
SettingInfo::RemoveSettingEventListener(*this);
+ __pInitMonitor->Enter();
+ __pInitMonitor->Notify();
+ __pInitMonitor->Exit();
+
return false;
}
projects / framework / osp / locations.git / commitdiff