Add new API definitions - checking & requesting policy for many privileges at once.

Change-Id: I91a0a52204ecf045bcbfa8897570e714979aebbc
Signed-off-by: Ernest Borowski <e.borowski@partner.samsung.com>

diff --git a/src/capi/impl/privacy_privilege_manager.c b/src/capi/impl/privacy_privilege_manager.c
index a009208..7545252 100644 (file)
--- a/src/capi/impl/privacy_privilege_manager.c
+++ b/src/capi/impl/privacy_privilege_manager.c
@@ -17,6 +17,7 @@
 /**
  * @file        privacy_privilege_manager.c
  * @author      Piotr Sawicki <p.sawicki2@partner.samsung.com>
+ * @author      Ernest Borowski <e.borowski@partner.samsung.com>
  * @brief       The implementation of Privacy Privilege Manager CAPI.
  */
 
@@ -291,6 +292,16 @@ int ppm_check_permission(const char *privilege, ppm_check_result_e *result)
 }
 
 EXPORT_API
+int ppm_check_permissions(const char **privileges, size_t privileges_count,
+                          ppm_check_result_e *results)
+{
+    (void)privileges;
+    (void)privileges_count;
+    (void)results;
+    return PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN;
+}
+
+EXPORT_API
 int ppm_request_permission(const char *privilege, ppm_request_response_cb callback, void *user_data)
 {
     if (!privilege || !callback) {
@@ -320,3 +331,14 @@ int ppm_request_permission(const char *privilege, ppm_request_response_cb callba
     return PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE;
 }
 
+EXPORT_API
+int ppm_request_permissions(const char **privileges, size_t privileges_count,
+                            ppm_request_multiple_response_cb callback,
+                            void *user_data)
+{
+    (void)privileges;
+    (void)privileges_count;
+    (void)callback;
+    (void)user_data;
+    return PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN;
+}

diff --git a/src/capi/include/privacy_privilege_manager.h b/src/capi/include/privacy_privilege_manager.h
index 23ee43c..2c7c55b 100644 (file)
--- a/src/capi/include/privacy_privilege_manager.h
+++ b/src/capi/include/privacy_privilege_manager.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
+ *  Copyright (c) 2017 - 2018 Samsung Electronics Co., Ltd All Rights Reserved
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -108,6 +108,30 @@ typedef void (*ppm_request_response_cb) (ppm_call_cause_e cause,
                                          void *user_data);
 
 /**
+ * @brief Called when the application receives a response upon calling ppm_request_permissions().
+ *
+ * @since_tizen 5.0
+ *
+ * @param[in]   cause             The value representing a reason why this callback
+ *                                has been called.
+ * @param[in]   results           The results of a response triggered by calling ppm_request_permissions().
+ *                                This is a valid value only if the @a cause parameter is equal to
+ *                                #PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER.
+ * @param[in]   privileges        The privileges array that has been checked. This pointer is managed
+ *                                by the API and it is valid only in the body of the callback function.
+ * @param[in]   privileges_count  The number of elements in the privileges and results arrays.
+ * @param[in]   user_data         User specific data, this pointer has been passed
+ *                                to ppm_request_permissions().
+ *
+ * @see ppm_request_permissions()
+ */
+typedef void (*ppm_request_multiple_response_cb) (ppm_call_cause_e cause,
+                                                  const ppm_request_result_e *results,
+                                                  const char **privileges,
+                                                  size_t privileges_count,
+                                                  void *user_data);
+
+/**
  * @brief Checks if an application, which calls this function, has permission to use the
  * given privilege.
  *
@@ -126,6 +150,28 @@ typedef void (*ppm_request_response_cb) (ppm_call_cause_e cause,
 int ppm_check_permission(const char *privilege, ppm_check_result_e *result);
 
 /**
+ * @brief Checks if an application, which calls this function, has permission to use the
+ * given privileges.
+ *
+ * @since_tizen 5.0
+ *
+ * @param[in]   privileges        The privileges array that is to be checked.
+ * @param[in]   privileges_count  The number of elements in the privileges and results arrays.
+ * @param[out]  results           The results of the privilege check. Caller is responsible for
+ *                                allocating this array with proper size and freeing it afterwards.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE               Successful
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR           I/O error
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER  Non unique privileges passed
+ * in first argument, privileges_count is more than 100 or other invalid parameter
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN            Unknown error
+ */
+int ppm_check_permissions(const char **privileges, size_t privileges_count,
+                          ppm_check_result_e *results);
+
+/**
  * @brief Requests a user's response to obtain permission for using the given privilege.
  *
  * @details When this function is called, an underlying service may show an appropriate
@@ -175,6 +221,58 @@ int ppm_request_permission(const char *privilege,
                            void *user_data);
 
 /**
+ * @brief Requests a user's response to obtain permission for using the given privileges.
+ *
+ * @details When this function is called, an underlying service may show an appropriate
+ * UI dialogue box (pop-up) with a question about granting the application access
+ * to the given privileges. Once a user makes a decision, the service may modify
+ * the privacy policy (when it is a definitive decision). After that, the service
+ * sends the response back to the application. The possible response values are as follows:\n
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER\n
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER\n
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE\n
+ * The application receives #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE value after
+ * pressing 'Deny' button while not having selected the 'Don't ask again?' checkbox. If the device
+ * has the home and back buttons, pressing either of them gives the
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE response.
+ * The application is informed about the user's decision by invoking ppm_request_multiple_response_cb().
+ * When a privacy policy for the given privileges has already been resolved, no pop-up will
+ * be shown and the service will reply immediately with an appropriate results:\n
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER\n
+ * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER\n
+ *
+ * @since_tizen 5.0
+ *
+ * @remarks Before calling this function, call ppm_check_permission() or ppm_check_permissions()
+ * to check if the application has permission to use the given privileges.
+ * This function should be called for each privilege with result
+ * #PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK returned from ppm_check_permission() or ppm_check_permissions().
+ *
+ * @param[in]   privileges        The given privileges array for which a pop-up must be shown.
+ * @param[in]   privileges_count  The number of elements in the privileges array.
+ * @param[in]   callback          The given callback function which will be invoked
+ *                                when the API receives a response.
+ * @param[in]   user_data         User specific data which will be passed to
+ *                                the given callback.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE                Successful
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR            I/O error
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER   Non unique privileges passed
+ * in first argument, privileges_count is more than 100 or other invalid parameter
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY       Out of memory
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS Operation already in progress
+ * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN             Unknown error
+ *
+ * @post ppm_request_multiple_response_cb() will be invoked.
+ * @see ppm_request_multiple_response_cb()
+ */
+int ppm_request_permissions(const char **privileges, size_t privileges_count,
+                            ppm_request_multiple_response_cb callback,
+                            void *user_data);
+
+
+/**
  * @}
  */