src/capi/include/privacy_privilege_manager.h

   1 /*
   2  *  Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Licensed under the Apache License, Version 2.0 (the "License");
   5  *  you may not use this file except in compliance with the License.
   6  *  You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *  Unless required by applicable law or agreed to in writing, software
  11  *  distributed under the License is distributed on an "AS IS" BASIS,
  12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *  See the License for the specific language governing permissions and
  14  *  limitations under the License
  15  */
  16
  17 #ifndef __PRIVACY_PRIVILEGE_MANAGER_H__
  18 #define __PRIVACY_PRIVILEGE_MANAGER_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @addtogroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE
  28  * @{
  29  */
  30
  31 /**
  32  * @brief Enumeration of error codes for Privacy Privilege Manager.
  33  * @since_tizen 4.0
  34  */
  35 typedef enum
  36 {
  37     /**< Successful */
  38     PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE                 = TIZEN_ERROR_NONE,
  39     /**< I/O error */
  40     PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR             = TIZEN_ERROR_IO_ERROR,
  41     /**< Invalid parameter */
  42     PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER    = TIZEN_ERROR_INVALID_PARAMETER,
  43     /**< Operation already in progress */
  44     PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS  = TIZEN_ERROR_ALREADY_IN_PROGRESS,
  45     /**< Out of memory */
  46     PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY        = TIZEN_ERROR_OUT_OF_MEMORY,
  47     /**< Unknown error */
  48     PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN              = TIZEN_ERROR_UNKNOWN,
  49 } ppm_error_e;
  50
  51 /**
  52  * @brief Enumeration of privilege check results.
  53  * @since_tizen 4.0
  54  */
  55 typedef enum {
  56     /**< An application has a privilege. */
  57     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW,
  58     /**< An application doesn't have a privilege. */
  59     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY,
  60     /**< A user has to be asked whether grant a privilege to an application or not. */
  61     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK,
  62 } ppm_check_result_e;
  63
  64 /**
  65  * @brief Enumeration of user decision results for the pop-up resonse callback.
  66  * @since_tizen 4.0
  67  */
  68 typedef enum {
  69     /**< A user granted a privilege to an application for an indefinite period of time. */
  70     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER,
  71     /**< A user did not grant a privilege to an application for an indefinite period of time. */
  72     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER,
  73     /**< A user did not grant a privilege to an application once. */
  74     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE,
  75 } ppm_popup_result_e;
  76
  77 /**
  78  * @brief Enumeration of status codes for the pop-up response callback.
  79  * @since_tizen 4.0
  80  */
  81 typedef enum {
  82     /**< Callback was called with a valid answer. */
  83     PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER,
  84     /**< Callback was called because of an error. */
  85     PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR,
  86 } ppm_call_cause_e;
  87
  88 /**
  89  * @brief Called when an application receives a response upon calling ppm_popup_request().
  90  *
  91  * @since_tizen 4.0
  92  *
  93  * @param[in]   cause       A value representing the reason why this callback
  94  *                          has been called.
  95  * @param[in]   result      A result of a response triggered by calling ppm_popup_request().
  96  *                          This is a valid value only if the @a cause parameter is equal to
  97  *                          **PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER**.
  98  * @param[in]   privilege   A privilege that has been checked.
  99  * @param[in]   user_data   User specific data, this parameter has been passed
 100  *                          to ppm_popup_request().
 101  *
 102  * @see ppm_popup_request()
 103  */
 104 typedef void (*ppm_popup_response_cb) (ppm_call_cause_e cause,
 105                                        ppm_popup_result_e result,
 106                                        const char *privilege,
 107                                        void *user_data);
 108
 109 /**
 110  * @brief Checks if an application, which calls this API, has permission for a
 111  * given privilege.
 112  *
 113  * @since_tizen 4.0
 114  *
 115  * @param[in]   privilege   A privilege that is to be checked.
 116  * @param[out]  result      A result of the privilege check.
 117  *
 118  * @return 0 on success, otherwise a negative error value
 119  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE               Successful
 120  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR           I/O error
 121  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER  Invalid parameter
 122  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY      Out of memory
 123  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN            Unknown error
 124  */
 125 int ppm_check_privilege(const char *privilege, ppm_check_result_e *result);
 126
 127 /**
 128  * @brief Requests a user's response to determine permission for a given privilege.
 129  *
 130  * @details When this function is called, an underlying service may show an appropriate
 131  * UI dialogue box (pop-up) with a question about granting the application access
 132  * to a given privilege. Once a user makes a decision, the service may modify
 133  * the privacy policy (when it is a definitive decision). After that, the service
 134  * sends the response back to the application. The possible response values are as follows:
 135  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or
 136  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER or
 137  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE.
 138  * The application is informed about the user's decision by invoking previously
 139  * registered ppm_popup_response_callback. When a privacy policy for the given privilege
 140  * has already been resolved, no pop-up will be shown and the service will return
 141  * a response immediately with an appropriate value:
 142  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or
 143  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER.
 144  *
 145  * @since_tizen 4.0
 146  *
 147  * @remarks Before calling this function, call ppm_check_privilege() to check
 148  * permission for a given privilege. If a result of calling ppm_check_privilege() is
 149  * **PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK**, an application should call
 150  * this function to determine whether a user allows the application to use
 151  * the privilege or not.
 152  *
 153  * @param[in]   privilege   A privilege for which a popup must be shown.
 154  * @param[in]   callback    A callback function which will be invoked
 155  *                          when the API receives a pop-up response.
 156  * @param[in]   user_data   User specific data which will be passed to
 157  *                          the registered callback.
 158  *
 159  * @return 0 on success, otherwise a negative error value
 160  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE                Successful
 161  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR            I/O error
 162  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER   Invalid parameter
 163  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY       Out of memory
 164  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS Operation already in progress
 165  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN             Unknown error
 166  *
 167  * @post ppm_popup_response_cb() will be invoked.
 168  * @see ppm_popup_response_cb()
 169  */
 170 int ppm_popup_request(const char *privilege,
 171                       ppm_popup_response_cb callback,
 172                       void *user_data);
 173
 174 /**
 175  * @}
 176  */
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif
 181
 182 #endif /* __PRIVACY_PRIVILEGE_MANAGER_H__ */