[ACR-656][MPR-657] Location batch APIs
[platform/core/api/location-manager.git] / include / locations.h
old mode 100644 (file)
new mode 100755 (executable)
index 752490d..a440454
@@ -44,8 +44,9 @@ typedef enum {
        LOCATIONS_ERROR_INCORRECT_METHOD                        = TIZEN_ERROR_LOCATION_MANAGER | 0x01,  /**< Location manager contains incorrect method for a given call */
        LOCATIONS_ERROR_NETWORK_FAILED                          = TIZEN_ERROR_LOCATION_MANAGER | 0x02,  /**< Network unavailable */
        LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE           = TIZEN_ERROR_LOCATION_MANAGER | 0x03,  /**< Location service is not available */
-       LOCATIONS_ERROR_GPS_SETTING_OFF                         = TIZEN_ERROR_LOCATION_MANAGER | 0x04,  /**< GPS/WPS setting is not enabled */
+       LOCATIONS_ERROR_GPS_SETTING_OFF                         = TIZEN_ERROR_LOCATION_MANAGER | 0x04,  /**< Setting for GPS, WPS, or MOCK is turned off */
        LOCATIONS_ERROR_SECURITY_RESTRICTED                     = TIZEN_ERROR_LOCATION_MANAGER | 0x05,  /**< Restricted by security system policy */
+       LOCATIONS_ERROR_SETTING_OFF                                     = LOCATIONS_ERROR_GPS_SETTING_OFF,              /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
 } location_error_e;
 
 
@@ -58,6 +59,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)*/
 } location_method_e;
 
 /**
@@ -84,6 +86,7 @@ typedef enum {
 } location_service_state_e;
 
 /**
+ * @deprecated Deprecated since 3.0
  * @brief Enumeration for the location service accessibility state.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  */
@@ -200,6 +203,7 @@ typedef void(*location_setting_changed_cb)(location_method_e method, bool enable
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] bounds           The location bounds handle
  * @param[in] user_data                The user data passed from the callback registration function
+ * @return @c true to continue with the next iteration of the loop, otherwise @c false to break out of the loop.
  * @pre location_manager_foreach_boundary() will invoke this callback.
  * @see location_manager_foreach_boundary()
  */
@@ -207,7 +211,7 @@ typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
 
 /**
  * @brief Called at defined interval with updated location information.
- * @since_tizen 2.4
+ * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] latitude         The updated latitude [-90.0 ~ 90.0] (degrees)
  * @param[in] longitude                The updated longitude [-180.0 ~ 180.0] (degrees)
  * @param[in] altitude         The updated altitude (meters)
@@ -224,6 +228,35 @@ typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
 
 /**
+ * @brief Called when the batch interval is expired.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @param[in] num_of_location  The number of location batch data
+ * @param[in] user_data                        The user data passed from the callback registration function
+ * @pre location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb()
+ * @see location_manager_start_batch()
+ * @see location_manager_set_location_batch_cb()
+ */
+typedef void(*location_batch_cb)(int num_of_location, void *user_data);
+
+/**
+ * @brief Gets iteratively to receive location batch data.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @param[in] latitude         The updated latitude [-90.0 ~ 90.0] (degrees)
+ * @param[in] longitude                The updated longitude [-180.0 ~ 180.0] (degrees)
+ * @param[in] altitude         The updated altitude (meters)
+ * @param[in] speed                    The updated speed (km/h)
+ * @param[in] direction                The updated direction (in degrees from the north)
+ * @param[in] horizontal       The horizontal accuracy (meters)
+ * @param[in] vertical         The vertical accuracy (meters)
+ * @param[in] timestamp                The timestamp (time when measurement took place or @c 0 if valid)
+ * @param[in] user_data                The user data passed from the callback registration function
+ * @return @c true to continue with the next iteration of the loop, otherwise @c false to break out of the loop.
+ * @pre location_manager_foreach_location_batch() will invoke this callback
+ * @see location_manager_foreach_location_batch()
+ */
+typedef bool(*location_batch_get_location_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data);
+
+/**
  * @brief Checks whether the given location method is available.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
@@ -255,7 +288,7 @@ int location_manager_is_enabled_method(location_method_e method, bool *enable);
 
 /**
  * @platform
- * @brief Enable the given location method.
+ * @brief Enables the given location method.
  * @since_tizen 2.3.1
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/location.enable
@@ -373,7 +406,7 @@ int location_manager_start(location_manager_h manager);
  * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
  * When that happens, the service is stopped and the user is notified.
  *
- * You can stop and start the location manager as needed.
+ * @remarks You can stop and start the location manager as needed.
  *
  * @param[in] manager          The location manager handle
  * @return 0 on success, otherwise a negative error value
@@ -630,6 +663,7 @@ int location_manager_get_last_velocity(location_manager_h manager, double *climb
 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
 
 /**
+ * @deprecated Deprecated since 3.0
  * @brief Gets the current application's location accessibility status.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[out] state           The current location service accessibility status.
@@ -806,7 +840,7 @@ int location_manager_get_distance(double start_latitude, double start_longitude,
 
 /**
  * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
- * @since_tizen 2.4
+ * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] manager          The location manager handle
  * @param[in] callback         The callback function to register
  * @param[in] interval         The minimum interval between position updates [1 ~ 120] (seconds)
@@ -824,7 +858,7 @@ int location_manager_set_distance_based_location_changed_cb(location_manager_h m
 
 /**
  * @brief Unregisters the callback function.
- * @since_tizen 2.4
+ * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] manager          The location manager handle
  * @return @c 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                               Successful
@@ -836,7 +870,7 @@ int location_manager_unset_distance_based_location_changed_cb(location_manager_h
 
 /**
  * @brief Registers a callback function to be invoked at defined interval with updated location information.
- * @since_tizen 2.4
+ * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] manager          The location manager handle
  * @param[in] callback         The callback function to register
  * @param[in] interval         The interval [1 ~ 120] (seconds)
@@ -853,7 +887,7 @@ int location_manager_set_location_changed_cb(location_manager_h manager, locatio
 
 /**
  * @brief      Unregisters the callback function.
- * @since_tizen 2.4
+ * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] manager          The location manager handle
  * @return @c 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                               Successful
@@ -864,6 +898,170 @@ int location_manager_set_location_changed_cb(location_manager_h manager, locatio
 int location_manager_unset_location_changed_cb(location_manager_h manager);
 
 /**
+ * @brief Registers a callback function to be invoked when batch_period is expired.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @remarks The batch_period should be greater than or equal to the batch_interval.
+ * @param[in] manager                  The location manager handle
+ * @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)
+ * @return @c 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
+ * @post location_batch_cb() will be invoked
+ * @see location_manager_start_batch()
+ * @see location_batch_cb()
+ * @see location_manager_unset_location_batch_cb()
+ */
+int location_manager_set_location_batch_cb(location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data);
+
+/**
+ * @brief Unregisters the callback function.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @param[in] manager                  The location manager handle
+ * @return @c 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_set_location_batch_cb()
+ */
+int location_manager_unset_location_batch_cb(location_manager_h manager);
+
+/**
+ * @brief Starts the location batch service.
+ * @details Calling this function starts location batch service, location_batch_cb() will be invoked every @a batch_period seconds.
+                       After that, you can obtain all locations with location_manager_foreach_location_batch().
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/location
+ * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
+ *             (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.
+ * @param[in] manager                  The location manager handle
+ * @return 0 on success, otherwise a negative error value
+ * @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
+ * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
+ * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                      Not supported
+ * @pre location_manager_set_location_batch_cb()
+ * @see location_manager_set_service_state_changed_cb()
+ * @see location_service_state_changed_cb()
+ * @see location_manager_foreach_location_batch()
+ * @see location_manager_stop_batch()
+ */
+int location_manager_start_batch(location_manager_h manager);
+
+/**
+ * @brief Stops the location batch service.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
+ * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
+ * @param[in] manager          The location manager handle
+ * @return 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE                                               Successful
+ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER                  Invalid parameter
+ * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE              Service not available
+ * @retval #LOCATIONS_ERROR_NETWORK_FAILED                             Network failed
+ * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                              Not supported
+ * @see location_manager_start_batch()
+ * @see location_manager_set_service_state_changed_cb()
+ * @see location_service_state_changed_cb()
+ */
+int location_manager_stop_batch(location_manager_h manager);
+
+/**
+ * @brief Retrieves all location information by invoking a specific callback for each location data.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @privlevel public
+ * @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
+ * @return     @c 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE                                               Successful
+ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER                  Invalid parameter
+ * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED  The application does not have the privilege to call this method
+ * @retval #LOCATIONS_ERROR_NOT_SUPPORTED                              Not supported
+ * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked
+ * @post location_batch_get_location_cb() will be invoked
+ * @see location_manager_start_batch()
+ * @see location_batch_cb()
+ * @see location_batch_get_location_cb()
+ */
+int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
+
+/**
+ * @brief Enables mock location.
+ * @remarks You can enable the mock location when developer mode is enabled.
+ * @since_tizen 3.0
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/location
+ * @param[in] enable           The value to set
+ * @return 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE Successful
+ * @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_set_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] 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] accuracy         The horizontal accuracy (meters)
+ * @return 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE                                       Successful
+ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER          Invalid argument
+ * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE      Service not available
+ * @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_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
+ * @param[in] manager          The location manager handle
+ * @return 0 on success, otherwise a negative error value
+ * @retval #LOCATIONS_ERROR_NONE                                       Successful
+ * @retval #LOCATIONS_ERROR_INVALID_PARAMETER          Invalid argument
+ * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE      Service not available
+ * @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_set_mock_location()
+ */
+int location_manager_clear_mock_location(location_manager_h manager);
+
+/**
  * @}
  */
 
@@ -972,13 +1170,10 @@ int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_s
 /**
  * @brief      Unregisters the callback function.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
- * @privlevel public
- * @privilege %http://tizen.org/privilege/location
  * @param[in] manager          The location manager handle
  * @return @c 0 on success, otherwise a negative error value
  * @retval #LOCATIONS_ERROR_NONE                               Successful
  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
- * @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 gps_status_set_satellite_updated_cb()
  */