From: jomui <jongmun.woo@samsung.com>
Date: Mon, 8 Aug 2016 10:32:09 +0000 (+0900)
Subject: [ACR-723] add new API and error about User Consent
X-Git-Tag: submit/tizen/20160824.005642~1^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=539d118bed2fbcb6ac85e2f03dde6b6aad5c56df;p=platform%2Fcore%2Fapi%2Fmaps-service.git

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

Signed-off-by: jomui <jongmun.woo@samsung.com>
Change-Id: I6464480eecce12410a85a424ff22255a0593a8b4
---

diff --git a/include/maps_error.h b/include/maps_error.h
index 0fd0f86..91b93be 100644
--- a/include/maps_error.h
+++ b/include/maps_error.h
@@ -79,6 +79,9 @@ typedef enum _maps_error_e {
 	MAPS_ERROR_UNKNOWN =
 		TIZEN_ERROR_UNKNOWN,			/**< Unknown error */
 
+	MAPS_ERROR_USER_NOT_CONSENTED =
+		TIZEN_ERROR_USER_NOT_CONSENTED,	/**< Not Consented (Since @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif) */
+
 	MAPS_ERROR_SERVICE_NOT_AVAILABLE =
 		TIZEN_ERROR_MAPS_SERVICE | 0x01,/**< Service unavailable */
 
diff --git a/include/maps_service.h b/include/maps_service.h
index fc0e1ad..dd5c655 100644
--- 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 */
@@ -147,6 +147,57 @@ typedef bool(*maps_service_provider_info_cb) (char *maps_provider,
 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
@@ -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.
  *