X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=include%2Flocations.h;h=952e27f550d1b839778a7d3a5152474069d6807b;hb=a8eab71b77cdb2cd0f43ebfe2094ee3944ca610a;hp=3715e6c6f3ea2ae2c55d7141dd820550fede010f;hpb=e961bdc7e9e1e96b78015788558d6ca48a979ac6;p=platform%2Fcore%2Fapi%2Flocation-manager.git diff --git a/include/locations.h b/include/locations.h old mode 100644 new mode 100755 index 3715e6c..952e27f --- a/include/locations.h +++ b/include/locations.h @@ -17,6 +17,7 @@ #ifndef __TIZEN_LOCATION_LOCATIONS_H__ #define __TIZEN_LOCATION_LOCATIONS_H__ +#include #include #include #include @@ -44,8 +45,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 +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_PASSIVE, /**< This method can be used to passively receive location updates without power consumption (Since 3.0)*/ } location_method_e; /** @@ -84,6 +87,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 */ @@ -196,10 +200,11 @@ typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data); /** - * @brief Gets called iteratively to notify you of location bounds. + * @brief Called once for each location bound. * @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 +212,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,14 +229,43 @@ 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. * @param[in] method The location method to be checked * @return @c true if the specified location method is supported, otherwise @c false if it is not available - * @exception #LOCATIONS_ERROR_NONE Successful - * @exception #LOCATIONS_ERROR_NOT_SUPPORTED Not supported - * @exception #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method + * @retval #LOCATIONS_ERROR_NONE Successful + * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported + * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method * @see location_manager_create() * @see location_manager_get_method() */ @@ -255,7 +289,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 @@ -312,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 @@ -373,7 +408,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 +665,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. @@ -639,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. @@ -806,7 +842,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 +860,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 +872,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 +889,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 +900,185 @@ 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) + * @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. + * @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 + * @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_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] 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_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 + * @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_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); + +/** * @} */ @@ -972,13 +1187,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() */