2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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
17 * @file csr-web-protection.h
18 * @author Dongsun Lee (ds73.lee@samsung.com)
20 * @brief Web Protection CAPI Header
22 #ifndef __CSR_WEB_PROTECTION_API_H_
23 #define __CSR_WEB_PROTECTION_API_H_
25 #include <csr-web-protection-types.h>
26 #include <csr-error.h>
34 * @addtogroup CAPI_CSR_FRAMEWORK_WP_MODULE
40 * @brief Initializes and returns a CSR Web Protection API handle.
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.
47 * @remarks @a handle should be released using csr_wp_context_destroy().
48 * @remarks Multiple handles can be obtained.
50 * @param[out] handle A pointer of CSR WP context handle.
52 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
59 * @see csr_wp_context_destroy()
61 int csr_wp_context_create(csr_wp_context_h *handle);
65 * @brief Releases all system resources associated with a Web Protection API handle.
69 * @param[in] handle CSR WP context handle returned by csr_wp_context_create().
71 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
80 * @see csr_wp_context_create()
82 int csr_wp_context_destroy(csr_wp_context_h handle);
86 * @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
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.
94 * @remarks This option is disabled(#CSR_WP_ASK_USER_NO) as a default.
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.
99 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
106 * @see csr_wp_context_create()
108 int csr_wp_set_ask_user(csr_wp_context_h handle, csr_wp_ask_user_e ask_user);
112 * @brief Sets a popup message of a client in case for a risky URL.
114 * @details Default message is "Risky URL which may harm your device is detected".
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.
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.
125 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
131 * @retval #CSR_ERROR_SYSTEM System error
133 * @see csr_wp_context_create()
135 int csr_wp_set_popup_message(csr_wp_context_h handle, const char *message);
139 * @brief Checks URL reputation against the engine vendor's database.
141 * @details Checks whether accessing the URL is risky or not and returns a result handle
142 * with the risk level for the URL.
146 * @privilege %http://tizen.org/privilege/antivirus.webprotect
148 * @remarks @a result will be released when @a handle is released using
149 * csr_wp_context_destroy().
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.
155 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
171 * @see csr_wp_context_create()
172 * @see csr_wp_set_ask_user()
173 * @see csr_wp_set_popup_message()
175 int csr_wp_check_url(csr_wp_context_h handle, const char *url,
176 csr_wp_check_result_h *result);
181 * @brief Extracts a risk level of the url from the result handle.
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.
188 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
195 * @see csr_wp_check_url()
197 int csr_wp_result_get_risk_level(csr_wp_check_result_h result, csr_wp_risk_level_e *level);
201 * @brief Extracts an url of vendor's web site that contains detailed information about
202 * the risk from the result handle.
206 * @remarks @a detailed_url must be released using free().
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
211 * If the risk level is #CSR_WP_RISK_MEDIUM or #CSR_WP_RISK_HIGH,
212 * this url should be provided by the engine.
214 * @return #CSR_ERROR_NONE on success, 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 detailed_url is invalid
219 * @retval #CSR_ERROR_SYSTEM System error
221 * @see csr_wp_check_url()
223 int csr_wp_result_get_detailed_url(csr_wp_check_result_h result, char **detailed_url);
227 * @brief Extracts a user response of a popup from the result handle.
231 * @param[in] result A result handle returned by csr_wp_check_url().
232 * @param[out] response A pointer of the user response.
234 * @return #CSR_ERROR_NONE on success, otherwise a negative error value
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
241 * @see csr_wp_check_url()
242 * @see #csr_wp_user_response_e
244 int csr_wp_result_get_user_response(csr_wp_check_result_h result,
245 csr_wp_user_response_e *response);