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