src/include/privilege_information.h

   1 /*
   2  * Copyright (c) 2014-2018 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
  18 #ifndef __TIZEN_SECURITY_PRIVILEGE_INFORMATION_H
  19 #define __TIZEN_SECURITY_PRIVILEGE_INFORMATION_H
  20
  21
  22 #include <tizen.h>
  23 #include <glib.h>
  24
  25 #ifndef TIZEN_DEPRECATED_API
  26 #define TIZEN_DEPRECATED_API __attribute__ ((__visibility__("default"), deprecated))
  27 #endif
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33
  34 /**
  35  * @addtogroup CAPI_SECURITY_FRAMEWORK_PRIVILEGE_INFO_MODULE
  36  * @{
  37  */
  38
  39
  40 /**
  41  * @brief Enumeration for error code for Privilege Information.
  42  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  43  */
  44 typedef enum {
  45         PRVINFO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  46         PRVINFO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid function parameter */
  47         PRVINFO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  48         PRVINFO_ERROR_INTERNAL_ERROR = TIZEN_ERROR_UNKNOWN, /**< Unknown error */
  49         PRVINFO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED /**< Not supported (Since 5.0) */
  50 } privilege_info_error_e;
  51
  52
  53 /**
  54  * @brief Gets the display name of the given privilege.
  55  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  56  * @remarks @a display_name must be released using free().
  57  * @param[in] api_version The API version of the application to get privilege information
  58  * @param[in] privilege The privilege
  59  * @param[out] display_name The display name of the privilege
  60  * @return @c 0 on success,
  61  *         otherwise a negative error value
  62  * @retval #PRVINFO_ERROR_NONE Successful
  63  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
  64  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
  65  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
  66  */
  67 int privilege_info_get_display_name(const char *api_version, const char *privilege, char **display_name);
  68
  69
  70 /**
  71  * @brief Gets the display name of the given privilege.
  72  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  73  * @remarks @a display_name must be released using free().
  74  * @remarks package_type must be one of followings: "PRVINFO_PACKAGE_TYPE_NATIVE", "PRVINFO_PACKAGE_TYPE_WEB"
  75  * @param[in] package_type The type of application package
  76  * @param[in] api_version The API version of the application to get privilege information
  77  * @param[in] privilege The privilege
  78  * @param[out] display_name The display name of the privilege
  79  * @return @c 0 on success,
  80  *         otherwise a negative error value
  81  * @retval #PRVINFO_ERROR_NONE Successful
  82  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
  83  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
  84  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
  85  */
  86 int privilege_info_get_display_name_by_pkgtype(const char *package_type, const char *api_version, const char *privilege, char **display_name);
  87
  88
  89 /**
  90  * @brief Gets the description of the given privilege.
  91  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  92  * @remarks @a description must be released using free().
  93  * @param[in] api_version The API version of the application to get privilege information
  94  * @param[in] privilege The privilege
  95  * @param[out] description The description of the privilege
  96  * @return @c 0 on success,
  97  *         otherwise a negative error value
  98  * @retval #PRVINFO_ERROR_NONE Successful
  99  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
 100  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 101  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
 102  */
 103 int privilege_info_get_description(const char *api_version, const char *privilege, char **description);
 104
 105
 106 /**
 107  * @brief Gets the description of the given privilege.
 108  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 109  * @remarks @a description must be released using free().
 110  * @remarks package_type must be one of followings: "PRVINFO_PACKAGE_TYPE_NATIVE", "PRVINFO_PACKAGE_TYPE_WEB"
 111  * @param[in] package_type The type of application package
 112  * @param[in] api_version The API version of the application to get privilege information
 113  * @param[in]  privilege The privilege
 114  * @param[out] description The description of the privilege
 115  * @return @c 0 on success,
 116  *         otherwise a negative error value
 117  * @retval #PRVINFO_ERROR_NONE Successful
 118  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
 119  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 120  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
 121  */
 122 int privilege_info_get_description_by_pkgtype(const char *package_type, const char *api_version, const char *privilege, char **description);
 123
 124
 125 /**
 126  * @brief Gets the display name of the privacy group in which the given privilege is included.
 127  * @since_tizen 3.0
 128  * @remarks @a privacy_name must be released using free().
 129  * @remarks @a privilege must be privacy related, otherwise #PRVINFO_ERROR_INVALID_PARAMETER is returned.
 130  * @param[in] privilege The privilege
 131  * @param[out] privacy_name The privacy group's display name that the given privilege is included in
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  * @retval #PRVINFO_ERROR_NONE Successful
 135  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
 136  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 137  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
 138  * @retval #PRVINFO_ERROR_NOT_SUPPORTED Not supported
 139  */
 140 int privilege_info_get_privacy_display_name(const char *privilege, char **privacy_name);
 141
 142
 143 /**
 144  * @deprecated Deprecated since 5.0. Use ppm_check_permission() instead. You can refer to @ref CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE.
 145  * @brief Gets the status of the given privacy related privilege.
 146  * @since_tizen 3.0
 147  * @remarks @a privilege must be privacy related, otherwise #PRVINFO_ERROR_INVALID_PARAMETER is returned.
 148  *          In case of errors, @a status is set to @c true.
 149  * @param[in] privilege The privilege
 150  * @param[out] status @c true if the privilege is on,
 151  *                    and @c false if the privilege is off
 152  * @return @c 0 on success,
 153  *         otherwise a negative error value
 154  * @retval #PRVINFO_ERROR_NONE Successful
 155  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 156  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
 157  * @retval #PRVINFO_ERROR_NOT_SUPPORTED Not supported
 158  */
 159 int privilege_info_get_privacy_privilege_status(const char *privilege, bool *status) TIZEN_DEPRECATED_API;
 160
 161
 162 /**
 163  * @brief The structure for privilege information.
 164  * @since_tizen 5.5
 165  */
 166 typedef struct _privilege_info_s {
 167         char* privilege_name; /**< The privilege name */
 168         char* display_name; /**< The display name of the privilege */
 169         char* description; /**< The description of the privilege */
 170 } privilege_info_s;
 171
 172 /**
 173  * @brief Enumeration for return code to be sent to consumer.
 174  * @since_tizen 5.5
 175  */
 176 typedef enum {
 177         PRIVILEGE_CONSUMER_RETURN_CODE_SUCCESS = 0, /**< Successful */
 178         PRIVILEGE_CONSUMER_RETURN_CODE_UNKNOWN_LOCALE_CODE, /**< Unknown locale code. */
 179         PRIVILEGE_CONSUMER_RETURN_CODE_INVALID_PARAMETER, /**< Invalid parameter. */
 180 } privilege_consumer_return_code_e;
 181
 182 /**
 183  * @brief Gets the privilege information list of the given locale and privileges.
 184  * @details If the given @a locale is not recognized, @a return_result is set to #PRIVILEGE_CONSUMER_RETURN_CODE_UNKNOWN_LOCALE_CODE and the result in the @a privilege_info_list is provided according to the current locale. If all of the privileges in @a privilege_name_list are invalid then @a return_result is set to #PRIVILEGE_CONSUMER_RETURN_CODE_INVALID_PARAMETER. Otherwise, @a return_result is set to #PRIVILEGE_CONSUMER_RETURN_CODE_SUCCESS. If some of the privileges in @a privilege_name_list are invalid then corresponding elements in the @a privilege_info_list will have the display_name and the description set to an empty string.
 185  * @since_tizen 5.5
 186  *
 187  * @remarks You must destroy the newly created privilege_info_list by calling privilege_info_free_privilege_info_list() if it is no longer needed.
 188  *
 189  * @param[in] locale The locale information
 190  * @param[in] privilege_name_list The privilege name list
 191  * @param[out] privilege_info_list The privilege information list of the given locale and privileges
 192  * @param[out] return_result The return code to be sent to consumer.
 193  *
 194  * @return 0 on success, otherwise a negative error value.
 195  *
 196  * @retval #PRVINFO_ERROR_NONE Successful
 197  * @retval #PRVINFO_ERROR_OUT_OF_MEMORY Out of memory
 198  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 199  * @retval #PRVINFO_ERROR_INTERNAL_ERROR Unknown error
 200  * @see privilege_info_free_privilege_info_list()
 201  * @see privilege_consumer_return_code_e
 202  */
 203 int privilege_info_get_privilege_info_list(const char* locale, GList* privilege_name_list, GList** privilege_info_list, privilege_consumer_return_code_e* return_result);
 204
 205 /**
 206  * @brief Destroys the privilege information list.
 207  * @since_tizen 5.5
 208  *
 209  * @remarks If @a privilege_info_list is NULL, no operation is performed and #PRVINFO_ERROR_INVALID_PARAMETER will be returned.
 210  *
 211  * @param[in] privilege_info_list The privilege information list to destroy
 212  *
 213  * @return 0 on success, otherwise a negative error value.
 214  *
 215  * @retval #PRVINFO_ERROR_NONE Successful
 216  * @retval #PRVINFO_ERROR_INVALID_PARAMETER Invalid function parameter
 217  */
 218 int privilege_info_free_privilege_info_list(GList* privilege_info_list);
 219
 220
 221
 222
 223 /**
 224  * @}
 225  */
 226
 227
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232
 233 #endif /* __TIZEN_SECURITY_PRIVILEGE_INFORMATION_H */