[ACR-723] add new API and error about User Consent

[platform/core/api/maps-service.git] / include / maps_service.h

diff --git a/include/maps_service.h b/include/maps_service.h
index fc0e1ad..dd5c655 100644 (file)
--- a/include/maps_service.h
+++ b/include/maps_service.h
@@ -67,7 +67,7 @@ typedef enum _maps_service_e {
        MAPS_SERVICE_SEARCH_PLACE_BY_AREA,              /**< Indicates that maps_service_search_place_by_area() service is allowed */
        MAPS_SERVICE_SEARCH_PLACE_BY_ADDRESS,   /**< Indicates that maps_service_search_place_by_address() service is allowed */
        MAPS_SERVICE_SEARCH_ROUTE,                              /**< Indicates that maps_service_search_route() service is allowed */
-       MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS,    /**< Indicates that maps_service_search_route_waypoints() service is allowed */
+       MAPS_SERVICE_SEARCH_ROUTE_WAYPOINTS,    /**< Indicates that maps_service_search_route_waypoints() service is allowed */
        MAPS_SERVICE_CANCEL_REQUEST,                    /**< Indicates that maps_service_cancel_request() service is allowed */
        MAPS_SERVICE_MULTI_REVERSE_GEOCODE,             /**< Indicates that maps_service_multi_reverse_geocode() service is allowed @if MOBILE (Since 3.0) @endif */
        MAPS_SERVICE_SEARCH_PLACE_LIST,                 /**< Indicates that maps_service_search_place_list() service is allowed @if MOBILE (Since 3.0) @endif */
@@ -148,6 +148,57 @@ int maps_service_foreach_provider(maps_service_provider_info_cb callback,
                                  void *user_data);
 
 /**
+ * @brief      Called with the information about user's consent.
+ * @details The Maps Service invokes this callback when the information about user's consent is obtained.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @param[in]  consented       The value of User Consent
+ * @param[in]  maps_provider   The name of Maps Provider
+ * @param[in]  user_data       The user data passed from maps_service_request_user_consent()
+ *
+ * @pre maps_service_request_user_consent() will invoke this callback.
+ *
+ * @see maps_service_request_user_consent()
+ * @see maps_service_create()
+ */
+typedef void(*maps_service_request_user_consent_cb) (bool consented,
+                                                               const char *maps_provider, void *user_data);
+
+/**
+ * @brief      Gets the user's consent to use maps data.
+ * @details The function gets information whether the user agreed that the application can use maps data.
+ * If maps_service_request_user_consent() is called when the user didn't agree yet, a popup is shown and
+ * the user can decide whether to agree or not. Then the result is saved and maps_service_request_user_consent_cb()
+ * is called. If the user has already agreed, the popup is not shown and only the callback is called.
+ * The request is asynchronous.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/mapservice
+ *
+ * @remarks Available map providers can be obtained with maps_service_foreach_provider().
+ *
+ * @param[in]  maps_provider   The name of Maps Provider
+ * @param[in]  callback        The callback which receives the user's consent decision
+ * @param[in]  user_data       The user data to be passed to the callback function
+ * @return     0 on success, otherwise a negative error value
+
+ * @retval     #MAPS_ERROR_NONE Successful
+ * @retval     #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval     #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
+ * @retval     #MAPS_ERROR_NOT_SUPPORTED Not supported
+ * @retval     #MAPS_ERROR_PERMISSION_DENIED Permission Denied
+ *
+ * @post This function invokes maps_service_request_user_consent_cb() to provide information
+ * about user consent.
+ *
+ * @see maps_service_foreach_provider()
+ * @see maps_service_request_user_consent_cb()
+ * @see maps_service_create()
+ */
+int maps_service_request_user_consent(const char *maps_provider,
+                                                               maps_service_request_user_consent_cb callback, void *user_data);
+
+/**
  * @brief      Creates a new Maps Service and assigns it with a handle.
  * @details While Maps Service is being created, a Maps Provider is initialized
  * and linked with Maps Service handle.
@@ -175,6 +226,7 @@ int maps_service_foreach_provider(maps_service_provider_info_cb callback,
  * @retval     #MAPS_ERROR_SERVICE_NOT_AVAILABLE Service not available
  * @retval     #MAPS_ERROR_NOT_SUPPORTED Not supported
  * @retval     #MAPS_ERROR_PERMISSION_DENIED Permission Denied
+ * @retval     #MAPS_ERROR_USER_NOT_CONSENTED The user did not consent
  *
  * @pre Call maps_service_foreach_provider() to get a available Maps Providers.
  *