[ACR-746] Passive Location

[platform/core/api/location-manager.git] / include / locations.h

diff --git a/include/locations.h b/include/locations.h
index a440454..952e27f 100755 (executable)
--- a/include/locations.h
+++ b/include/locations.h
@@ -17,6 +17,7 @@
 #ifndef __TIZEN_LOCATION_LOCATIONS_H__
 #define __TIZEN_LOCATION_LOCATIONS_H__
 
+#include <tizen.h>
 #include <tizen_type.h>
 #include <tizen_error.h>
 #include <time.h>
@@ -59,7 +60,7 @@ typedef enum {
        LOCATIONS_METHOD_HYBRID,        /**< This method selects the best method available at the moment */
        LOCATIONS_METHOD_GPS,           /**< This method uses Global Positioning System */
        LOCATIONS_METHOD_WPS,           /**< This method uses WiFi Positioning System */
-       LOCATIONS_METHOD_MOCK,          /**< This method uses mock location for testing (Since 3.0)*/
+       LOCATIONS_METHOD_PASSIVE,       /**< This method can be used to passively receive location updates without power consumption (Since 3.0)*/
 } location_method_e;
 
 /**
@@ -345,6 +346,7 @@ int location_manager_destroy(location_manager_h manager);
  * @param[in] user_data                The user data to be passed to the callback function
  * @retval #LOCATIONS_ERROR_NONE                                               Successful
  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER                  Invalid parameter
+ * @retval #LOCATIONS_ERROR_INCORRECT_METHOD                   Incorrect method
  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE              Service not available
  * @retval #LOCATIONS_ERROR_NETWORK_FAILED                             Network failed
  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF                            GPS is not enabled
@@ -673,7 +675,7 @@ int location_manager_get_last_accuracy(location_manager_h manager, location_accu
  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER          Invalid argument
  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                      Not supported
  */
-int location_manager_get_accessibility_state(location_accessibility_state_e *state);
+int location_manager_get_accessibility_state(location_accessibility_state_e *state) TIZEN_DEPRECATED_API;
 
 /**
  * @brief Registers a callback function to be invoked at defined interval with updated position information.
@@ -905,6 +907,7 @@ int location_manager_unset_location_changed_cb(location_manager_h manager);
  * @param[in] callback                 The callback function to register
  * @param[in] batch_interval   The batch sampling interval [1 ~ 255] (seconds)
  * @param[in] batch_period             The batch period [1 ~ 60000] (seconds)
+ * @param[in] user_data                        The user data to be passed to the callback function
  * @return @c 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                               Successful
  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
@@ -980,7 +983,7 @@ int location_manager_stop_batch(location_manager_h manager);
  * @privilege %http://tizen.org/privilege/location
  * @param[in] manager          The location manager handle
  * @param[in] callback         The iteration callback function
- * @param[in] user_data                The user data passed from the callback registration function
+ * @param[in] user_data                The user data to be passed to the callback function
  * @return     @c 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                                               Successful
  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER                  Invalid parameter
@@ -995,8 +998,24 @@ int location_manager_stop_batch(location_manager_h manager);
 int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
 
 /**
+ * @brief Checks whether the mock location is enabled.
+ * @since_tizen 3.0
+ * @param[out] enabled         Indicates whether the mock location is enabled
+ * @return 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE Successful
+ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
+ * @retval #LOCATIONS_ERROR_NOT_SUPPORTED      Not supported
+ * @see location_manager_enable_mock_location()
+ * @see location_manager_set_mock_location()
+ * @see location_manager_clear_mock_location()
+ */
+int location_manager_is_enabled_mock_location(bool *enabled);
+
+/**
  * @brief Enables mock location.
- * @remarks You can enable the mock location when developer mode is enabled.
+ * @details The mock location is a testing function to make location API and callback deliver a mock location
+ * set by location_manager_set_mock_location() instead of real positioning data even in the other applications.
+ * @remarks The mock location can only be enabled if developer mode is enabled.
  * @since_tizen 3.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/location
@@ -1006,25 +1025,24 @@ int location_manager_foreach_location_batch(location_manager_h manager, location
  * @retval #LOCATIONS_ERROR_SETTING_OFF        MOCK location is not enabled
  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED      Not supported
- * @see location_manager_is_enabled_method()
- * @see location_manager_create()
+ * @see location_manager_is_enabled_mock_location()
  * @see location_manager_set_mock_location()
+ * @see location_manager_clear_mock_location()
  */
 int location_manager_enable_mock_location(const bool enable);
 
 /**
  * @brief Sets a mock location for the given location method.
  * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical accuracy.
- *
  * @since_tizen 3.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/location
  * @param[in] manager          The location manager handle
  * @param[in] latitude         The current latitude [-90.0 ~ 90.0] (degrees)
- * @param[in] longitude        The current longitude [-180.0 ~ 180.0] (degrees)
+ * @param[in] longitude                The current longitude [-180.0 ~ 180.0] (degrees)
  * @param[in] altitude         The current altitude (meters)
- * @param[in] speed            The speed (km/h)
- * @param[in] direction        The direction, degrees from the north [0.0 ~ 360.0]
+ * @param[in] speed                    The speed (km/h)
+ * @param[in] direction                The direction, degrees from the north [0.0 ~ 360.0]
  * @param[in] accuracy         The horizontal accuracy (meters)
  * @return 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                                       Successful
@@ -1033,16 +1051,15 @@ int location_manager_enable_mock_location(const bool enable);
  * @retval #LOCATIONS_ERROR_SETTING_OFF                                MOCK location is not enabled
  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                      Not supported
- * @see location_manager_is_enabled_method()
- * @see location_manager_enable_mock_location()
  * @see location_manager_create()
+ * @see location_manager_is_enabled_mock_location()
+ * @see location_manager_enable_mock_location()
  * @see location_manager_clear_mock_location()
  */
 int location_manager_set_mock_location(location_manager_h manager, const double latitude, const double longitude, const double altitude, const double speed, const double direction, const double accuracy);
 
 /**
  * @brief Clears a mock location.
- *
  * @since_tizen 3.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/location
@@ -1054,9 +1071,9 @@ int location_manager_set_mock_location(location_manager_h manager, const double
  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
  * @retval #LOCATIONS_ERROR_SETTING_OFF                                MOCK location is not enabled
  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                      Not supported
- * @see location_manager_is_enabled_method()
- * @see location_manager_enable_mock_location()
  * @see location_manager_create()
+ * @see location_manager_is_enabled_mock_location()
+ * @see location_manager_enable_mock_location()
  * @see location_manager_set_mock_location()
  */
 int location_manager_clear_mock_location(location_manager_h manager);