#ifndef __TIZEN_LOCATION_LOCATIONS_H__
#define __TIZEN_LOCATION_LOCATIONS_H__
+#include <tizen.h>
#include <tizen_type.h>
#include <tizen_error.h>
#include <time.h>
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;
/**
* @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()
*/
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.
* @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
* @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.
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)
+ * @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
+ * @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 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
+ * @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 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
* @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
* @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
* @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);
projects / platform / core / api / location-manager.git / blobdiff