src/include/csr/csr-web-protection.h

   1 /*
   2  *  Copyright (c) 2016 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  * @file        csr-web-protection.h
  18  * @author      Dongsun Lee (ds73.lee@samsung.com)
  19  * @version     1.0
  20  * @brief       Web Protection CAPI Header
  21  */
  22 #ifndef __CSR_WEB_PROTECTION_API_H_
  23 #define __CSR_WEB_PROTECTION_API_H_
  24
  25 #include <csr-web-protection-types.h>
  26 #include <csr-error.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32
  33 /**
  34  * @addtogroup CAPI_CSR_FRAMEWORK_WP_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @partner
  40  * @brief Initializes and returns a CSR Web Protection API handle.
  41  *
  42  * @details A Web Protection API handle (or CSR WP handle) is obtained by this method.
  43  *          The handle is required for subsequent CSR WP API calls.
  44  *
  45  * @since_tizen 3.0
  46  *
  47  * @remarks The @a handle should be released using csr_wp_context_destroy().
  48  * @remarks Multiple handles can be obtained.
  49  *
  50  * @param[out] handle A pointer of CSR WP context handle.
  51  *
  52  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  53  *
  54  * @retval #CSR_ERROR_NONE                  Successful
  55  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
  56  * @retval #CSR_ERROR_INVALID_PARAMETER     @a handle is invalid
  57  * @retval #CSR_ERROR_SYSTEM                System error
  58  *
  59  * @see csr_wp_context_destroy()
  60  */
  61 int csr_wp_context_create(csr_wp_context_h *handle);
  62
  63 /**
  64  * @partner
  65  * @brief Releases all system resources associated with a Web Protection API handle.
  66  *
  67  * @since_tizen 3.0
  68  *
  69  * @param[in] handle CSR WP context handle returned by csr_wp_context_create().
  70  *
  71  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  72  *
  73  * @retval #CSR_ERROR_NONE                  Successful
  74  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
  75  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
  76  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
  77  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
  78  * @retval #CSR_ERROR_SYSTEM                System error
  79  *
  80  * @see csr_wp_context_create()
  81  */
  82 int csr_wp_context_destroy(csr_wp_context_h handle);
  83
  84 /**
  85  * @partner
  86  * @brief Sets a popup option for risky URL checked.
  87  *
  88  * @details If #CSR_WP_ASK_USER_YES is set, a popup will be prompted to a user when a URL
  89  *          turns out risky. If #CSR_WP_ASK_USER_NO is set, no popup will be prompted
  90  *          even when a URL turns out risky.
  91  *
  92  * @since_tizen 3.0
  93  *
  94  * @remarks This option is disabled(#CSR_WP_ASK_USER_NO) as a default.
  95  *
  96  * @param[in] handle    CSR WP context handle returned by csr_wp_context_create().
  97  * @param[in] ask_user  A popup option in case for a risky URL.
  98  *
  99  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 100  *
 101  * @retval #CSR_ERROR_NONE                  Successful
 102  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 103  * @retval #CSR_ERROR_INVALID_PARAMETER     @a ask_user is invalid
 104  * @retval #CSR_ERROR_SYSTEM                System error
 105  *
 106  * @see csr_wp_context_create()
 107  */
 108 int csr_wp_set_ask_user(csr_wp_context_h handle, csr_wp_ask_user_e ask_user);
 109
 110 /**
 111  * @partner
 112  * @brief Sets a popup message of a client in case for a risky URL.
 113  *
 114  * @details Default message is "Risky URL which may harm your device is detected".
 115  *
 116  * @since_tizen 3.0
 117  *
 118  * @remarks Meaningful only when ask user option is set by csr_wp_set_ask_user().
 119  * @remarks The message will be printed on popup for user.
 120  * @remarks Default popup message will be used if it isn't set.
 121  *
 122  * @param[in] handle   CSR WP context handle returned by csr_wp_context_create().
 123  * @param[in] message  A message to print on a popup.
 124  *
 125  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 126  *
 127  * @retval #CSR_ERROR_NONE                  Successful
 128  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 129  * @retval #CSR_ERROR_INVALID_PARAMETER     @a message is too long or empty. Max size
 130  *                                          is 64 bytes.
 131  * @retval #CSR_ERROR_SYSTEM                System error
 132  *
 133  * @see csr_wp_context_create()
 134  */
 135 int csr_wp_set_popup_message(csr_wp_context_h handle, const char *message);
 136
 137 /**
 138  * @partner
 139  * @brief Checks URL reputation against the engine vendor's database.
 140  *
 141  * @details Checks whether accessing the URL is risky or not and returns a result handle
 142  *          with the risk level for the URL.
 143  *
 144  * @since_tizen 3.0
 145  * @privlevel partner
 146  * @privilege %http://tizen.org/privilege/antivirus.webprotect
 147  *
 148  * @remarks The @a result will be released when @a handle is released using
 149  *          csr_wp_context_destroy().
 150  *
 151  * @param[in]  handle   CSR WP context handle returned by csr_wp_context_create().
 152  * @param[in]  url      URL to check.
 153  * @param[out] result   A pointer of the result handle with the Risk level for the URL.
 154  *
 155  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 156  *
 157  * @retval #CSR_ERROR_NONE                  Successful
 158  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 159  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 160  * @retval #CSR_ERROR_PERMISSION_DENIED     Permission denied
 161  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 162  * @retval #CSR_ERROR_INVALID_PARAMETER     @a url or @a result is invalid
 163  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 164  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 165  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 166  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 167  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 168  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 169  * @retval #CSR_ERROR_SYSTEM                System error
 170  *
 171  * @see csr_wp_context_create()
 172  * @see csr_wp_set_ask_user()
 173  * @see csr_wp_set_popup_message()
 174  */
 175 int csr_wp_check_url(csr_wp_context_h handle, const char *url,
 176                                          csr_wp_check_result_h *result);
 177
 178
 179 /**
 180  * @partner
 181  * @brief Extracts a risk level of the url from the result handle.
 182  *
 183  * @since_tizen 3.0
 184  *
 185  * @param[in]  result  A result handle returned by csr_wp_check_url().
 186  * @param[out] level   A pointer of the risk level for the given URL.
 187  *
 188  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 189  *
 190  * @retval #CSR_ERROR_NONE                 Successful
 191  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 192  * @retval #CSR_ERROR_INVALID_PARAMETER    @a level is invalid
 193  * @retval #CSR_ERROR_SYSTEM               System error
 194  *
 195  * @see csr_wp_check_url()
 196  */
 197 int csr_wp_result_get_risk_level(csr_wp_check_result_h result, csr_wp_risk_level_e *level);
 198
 199 /**
 200  * @partner
 201  * @brief Extracts an url of vendor's web site that contains detailed information about
 202  *        the risk from the result handle.
 203  *
 204  * @since_tizen 3.0
 205  *
 206  * @remarks  The @a detailed_url must be released using free().
 207  *
 208  * @param[in]  result        A result handle returned by csr_wp_check_url().
 209  * @param[out] detailed_url  A pointer of an url that contains detailed information about
 210  *                           the risk.
 211  *                           If the risk level is #CSR_WP_RISK_MEDIUM or #CSR_WP_RISK_HIGH,
 212  *                           this url should be provided by the engine.
 213  *
 214  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 215  *
 216  * @retval #CSR_ERROR_NONE                 Successful
 217  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 218  * @retval #CSR_ERROR_INVALID_PARAMETER    @a detailed_url is invalid
 219  * @retval #CSR_ERROR_SYSTEM               System error
 220  *
 221  * @see csr_wp_check_url()
 222  */
 223 int csr_wp_result_get_detailed_url(csr_wp_check_result_h result, char **detailed_url);
 224
 225 /**
 226  * @partner
 227  * @brief Extracts a user response of a popup from the result handle.
 228  *
 229  * @since_tizen 3.0
 230  *
 231  * @param[in]  result     A result handle returned by csr_wp_check_url().
 232  * @param[out] response   A pointer of the user response.
 233  *
 234  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 235  *
 236  * @retval #CSR_ERROR_NONE                 Successful
 237  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 238  * @retval #CSR_ERROR_INVALID_PARAMETER    @a response is invalid
 239  * @retval #CSR_ERROR_SYSTEM               System error
 240  *
 241  * @see csr_wp_check_url()
 242  * @see #csr_wp_user_response_e
 243  */
 244 int csr_wp_result_get_user_response(csr_wp_check_result_h result,
 245                                                                         csr_wp_user_response_e *response);
 246
 247
 248 /**
 249  * @}
 250  */
 251
 252 #ifdef __cplusplus
 253 }
 254 #endif
 255
 256 #endif