src/include/csr/csr-content-screening.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-content-screening.h
  18  * @author      Dongsun Lee (ds73.lee@samsung.com)
  19  * @version     1.0
  20  * @brief       Main API header for content screening
  21  */
  22 #ifndef __CSR_CONTENT_SCREENING_API_H_
  23 #define __CSR_CONTENT_SCREENING_API_H_
  24
  25 #include <time.h>
  26 #include <stdbool.h>
  27 #include <stddef.h>
  28
  29 #include <csr-content-screening-types.h>
  30 #include <csr-error.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @brief Initializes and returns a Malware Screening API handle.
  38  *
  39  * @since_tizen 3.0
  40  *
  41  * @remarks A Malware Screening API handle (or CSR CS handle) is obtained using the
  42  *          csr_cs_context_create() function. The handle is required for subsequent
  43  *          CSR CS API calls. The csr_cs_context_destroy() function releases/closes
  44  *          the handle. Multiple handles can be obtained using csr_cs_context_create().
  45  *
  46  * @param[out] phandle A pointer of CSR CS context handle.
  47  *
  48  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  49  *
  50  * @retval #CSR_ERROR_NONE                  Successful
  51  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
  52  * @retval #CSR_ERROR_INVALID_PARAMETER     phandle is invalid
  53  * @retval #CSR_ERROR_PERMISSION_DENIED     Permission denied
  54  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
  55  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
  56  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
  57  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
  58  */
  59 int csr_cs_context_create(csr_cs_context_h *phandle);
  60
  61 /**
  62  * @brief Releases all system resources associated with a Malware Screening API handle.
  63  *
  64  * @since_tizen 3.0
  65  *
  66  * @param[in] handle CSR CS context handle returned by csr_cs_context_create().
  67  *
  68  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  69  *
  70  * @retval #CSR_ERROR_NONE                  Successful
  71  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
  72  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
  73  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
  74  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
  75  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
  76  */
  77 int csr_cs_context_destroy(csr_cs_context_h handle);
  78
  79 /**
  80  * @brief Sets a popup option in case that a malware is detected.
  81  *
  82  * @since_tizen 3.0
  83  *
  84  * @remarks If #CSR_CS_ASK_USER is set, a popup will be prompted to a user when a malware
  85  *          is detected(#CSR_CS_SEVERITY_MEDIUM or #CSR_CS_SEVERITY_HIGH). If
  86  *          #CSR_CS_NOT_ASK_USER is set, no popup will be prompted even when a malware is
  87  *          detected. The default value of this option is #CSR_CS_ASK_USER. When a user
  88  *          selects to remove a detected malicious content, the content will be removed
  89  *          only if the client has the permission to remove the content.
  90  *
  91  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
  92  * @param[in] ask_user  A popup option in case for a risky URL.
  93  *
  94  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  95  *
  96  * @retval #CSR_ERROR_NONE                  Successful
  97  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
  98  * @retval #CSR_ERROR_INVALID_PARAMETER     ask_user is invalid
  99  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 100  */
 101 int csr_cs_set_ask_user(csr_cs_context_h handle, csr_cs_ask_user_e ask_user);
 102
 103 /**
 104  * @brief Sets a popup message of a client in case that a malware is detected.
 105  *
 106  * @since_tizen 3.0
 107  *
 108  * @remarks When a popup is prompted to a user, the message set by this method will be
 109  *          shown. When a client doesn't set his own popup message, the default message
 110  *          will be shown in the popup.
 111  *
 112  * @param[in] handle  CSR CS context handle returned by csr_cs_context_create().
 113  * @param[in] message a message in a popup.
 114  *
 115  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 116  *
 117  * @retval #CSR_ERROR_NONE                  Successful
 118  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 119  * @retval #CSR_ERROR_INVALID_PARAMETER     @a message is too long or empty. Max size
 120  *                                          is 64 bytes.
 121  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 122  *
 123  * @see csr_cs_context_create()
 124  */
 125 int csr_cs_set_popup_message(csr_cs_context_h handle, const char *message);
 126
 127 /**
 128  * @brief Sets a maxium core usage during scanning.
 129  *
 130  * @since_tizen 3.0
 131  *
 132  * @remarks If a core usage is not set, CSR_CS_USE_CORE_DEFAULT will be used.
 133  *
 134  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 135  * @param[in] usage     A maxium core usage during scanning.
 136  *
 137  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 138  *
 139  * @retval #CSR_ERROR_NONE                  Successful
 140  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 141  * @retval #CSR_ERROR_INVALID_PARAMETER     usage is invalid
 142  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 143  */
 144 int csr_cs_set_core_usage(csr_cs_context_h handle, csr_cs_core_usage_e usage);
 145
 146 /**
 147  * @brief Sets a database which is used in scanning.
 148  *
 149  * @since_tizen 3.0
 150  *
 151  * @remarks If a database is not set or an engine does not support "scanning on cloud",
 152  *          the scanning will be done in a local device.
 153  *
 154  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 155  *
 156  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 157  *
 158  * @retval #CSR_ERROR_NONE                  Successful
 159  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 160  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 161  */
 162 int csr_cs_set_scan_on_cloud(csr_cs_context_h handle);
 163
 164 /**
 165  * @brief Main function for caller to scan a data buffer for malware.
 166  *
 167  * @since_tizen 3.0
 168  * @privlevel partner
 169  * @privilege %http://tizen.org/privilege/antivirus.scan
 170  *
 171  * @remarks  Scan data synchronously.
 172  *
 173  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 174  * @param[in]  data       A scan target data.
 175  * @param[in]  length     A size of a scan target data.
 176  * @param[out] pdetected  A pointer of the detected malware handle. It can be null when no malware detected.
 177  *
 178  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 179  *
 180  * @retval #CSR_ERROR_NONE                  Successful
 181  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 182  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 183  * @retval #CSR_ERROR_INVALID_PARAMETER     data or presult is invalid
 184  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 185  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 186  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 187  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 188  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 189  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 190  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 191  */
 192 int csr_cs_scan_data(csr_cs_context_h handle,
 193                                          const unsigned char *data,
 194                                          size_t length,
 195                                          csr_cs_detected_h *pdetected);
 196
 197 /**
 198  * @brief Main function for caller to scan a file specified by file path for malware.
 199  *
 200  * @since_tizen 3.0
 201  * @privlevel partner
 202  * @privilege %http://tizen.org/privilege/antivirus.scan
 203  *
 204  * @remarks  Scan file synchronously.
 205  *
 206  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 207  * @param[in]  file_path  A path of scan target file.
 208  * @param[out] pdetected  A pointer of the detected malware handle. It can be null when no malware detected.
 209  *
 210  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 211  *
 212  * @retval #CSR_ERROR_NONE                  Successful
 213  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 214  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 215  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or presult is invalid
 216  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 217  * @retval #CSR_ERROR_REMOVE_FAILED         File remove failed when malware exist and
 218  *                                          user select to remove by popup. @a pdetected
 219  *                                          will be allocated on this error unlike others.
 220  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 221  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 222  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 223  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 224  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 225  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 226  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 227  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 228  */
 229 int csr_cs_scan_file(csr_cs_context_h handle,
 230                                          const char *file_path,
 231                                          csr_cs_detected_h *pdetected);
 232
 233 /**
 234  * @brief Sets a callback function for detection of a malware.
 235  *
 236  * @since_tizen 3.0
 237  *
 238  * @remarks Callback for asynchronous scan function.
 239  *
 240  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 241  * @param[in] callback  a callback function for detection of a malware.
 242  *
 243  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 244  *
 245  * @retval #CSR_ERROR_NONE                  Successful
 246  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 247  * @retval #CSR_ERROR_INVALID_PARAMETER     callback is invalid
 248  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 249  */
 250 int csr_cs_set_callback_on_detected(csr_cs_context_h handle,
 251                                                                         csr_cs_on_detected_cb callback);
 252
 253 /**
 254  * @brief Sets a callback function for scanning completed without an error.
 255  *
 256  * @since_tizen 3.0
 257  *
 258  * @remarks Callback for asynchronous scan function.
 259  *
 260  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 261  * @param[in] callback  a callback function for scanning completed without an error.
 262  *
 263  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 264  *
 265  * @retval #CSR_ERROR_NONE                  Successful
 266  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 267  * @retval #CSR_ERROR_INVALID_PARAMETER     callback is invalid
 268  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 269  */
 270 int csr_cs_set_callback_on_completed(csr_cs_context_h handle,
 271                                                                          csr_cs_on_completed_cb callback);
 272
 273 /**
 274  * @brief Sets a callback function for scanning cancelled.
 275  *
 276  * @since_tizen 3.0
 277  *
 278  * @remarks Callback for asynchronous scan function.
 279  *
 280  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 281  * @param[in] callback  a callback function for scanning cancelled.
 282  *
 283  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 284  *
 285  * @retval #CSR_ERROR_NONE                  Successful
 286  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 287  * @retval #CSR_ERROR_INVALID_PARAMETER     callback is invalid
 288  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 289  */
 290 int csr_cs_set_callback_on_cancelled(csr_cs_context_h handle,
 291                                                                          csr_cs_on_cancelled_cb callback);
 292
 293 /**
 294  * @brief Sets a callback function for scanning stopped with an error.
 295  *
 296  * @since_tizen 3.0
 297  *
 298  * @remarks Callback for asynchronous scan function.
 299  *
 300  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 301  * @param[in] callback  a callback function for scanning stopped with an error.
 302  *
 303  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 304  *
 305  * @retval #CSR_ERROR_NONE                  Successful
 306  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 307  * @retval #CSR_ERROR_INVALID_PARAMETER     callback is invalid
 308  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 309  */
 310 int csr_cs_set_callback_on_error(csr_cs_context_h handle,
 311                                                                  csr_cs_on_error_cb callback);
 312
 313
 314 /**
 315  * @brief Sets a callback function for the case that a file scan is completed.
 316  *
 317  * @since_tizen 3.0
 318  *
 319  * @remarks Callback for asynchronous scan function.
 320  *
 321  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 322  * @param[in] callback  a callback function for the case that a file scan is completed.
 323  *
 324  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 325  *
 326  * @retval #CSR_ERROR_NONE                  Successful
 327  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 328  * @retval #CSR_ERROR_INVALID_PARAMETER     callback is invalid
 329  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 330  */
 331 int csr_cs_set_callback_on_file_scanned(csr_cs_context_h handle,
 332                                                                                 csr_cs_on_file_scanned_cb callback);
 333
 334 /**
 335  * @brief Main function for caller to scan files specified by an array of file paths
 336  *        for malware.
 337  *
 338  * @since_tizen 3.0
 339  * @privlevel partner
 340  * @privilege %http://tizen.org/privilege/antivirus.scan
 341  *
 342  * @remarks  Asynchronous function. The caller should set callback functions before
 343  *           calls this.
 344  *
 345  * @param[in]  handle       CSR CS context handle returned by csr_cs_context_create().
 346  * @param[in]  file_paths   An array of scan target files.
 347  * @param[in]  count        A number of scan target files.
 348  * @param[in]  user_data    The pointer of a user data. It can be null.\n
 349  *                          It is delivered back to the client when a callback function is called.
 350  *
 351  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 352  *
 353  * @retval #CSR_ERROR_NONE                  Successful
 354  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 355  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 356  * @retval #CSR_ERROR_INVALID_PARAMETER     file_paths or count is invalid
 357  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 358  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 359  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 360  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 361  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 362  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 363  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 364  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 365  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 366  */
 367 int csr_cs_scan_files_async(csr_cs_context_h handle,
 368                                                         const char *file_paths[],
 369                                                         size_t count,
 370                                                         void *user_data);
 371
 372 /**
 373  * @brief Main function for caller to scan a directoy specified by
 374  *        directory path for malware.
 375  *
 376  * @since_tizen 3.0
 377  * @privlevel partner
 378  * @privilege %http://tizen.org/privilege/antivirus.scan
 379  *
 380  * @remarks  Asynchronous function. The caller should set callback functions before calls
 381  *           this. All files under target directory which can be accessed by a client are
 382  *           scanned.
 383  *
 384  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 385  * @param[in]  dir_path   A path of scan target directory.
 386  * @param[in]  user_data  The pointer of a user data. It can be null.\n
 387  *                        It is delivered back to the client when a callback function is called.
 388  *
 389  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 390  *
 391  * @retval #CSR_ERROR_NONE                  Successful
 392  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 393  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 394  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or presult is invalid
 395  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 396  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 397  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 398  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 399  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 400  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 401  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 402  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 403  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 404  */
 405 int csr_cs_scan_dir_async(csr_cs_context_h handle,
 406                                                   const char *dir_path,
 407                                                   void *user_data);
 408
 409 /**
 410  * @brief Main function for caller to scan directories specified by
 411  *        an array of directory paths for malware.
 412  *
 413  * @since_tizen 3.0
 414  * @privlevel partner
 415  * @privilege %http://tizen.org/privilege/antivirus.scan
 416  *
 417  * @remarks  Asynchronous function. The caller should set callback functions before calls
 418  *           this. All files under target directories which can be accessed by a client
 419  *           are scanned.
 420  *
 421  * @param[in]  handle       CSR CS context handle returned by csr_cs_context_create().
 422  * @param[in]  dir_paths    An array of scan target directories.
 423  * @param[in]  count        A number of scan target directories.
 424  * @param[in]  user_data    The pointer of a user data. It can be null.
 425  *                          It is delivered back to the client when a callback
 426  *                          function is called.
 427  *
 428  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 429  *
 430  * @retval #CSR_ERROR_NONE                  Successful
 431  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 432  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 433  * @retval #CSR_ERROR_INVALID_PARAMETER     dir_paths or count is invalid
 434  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 435  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 436  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 437  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 438  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 439  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 440  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 441  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 442  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 443  */
 444 int csr_cs_scan_dirs_async(csr_cs_context_h handle,
 445                                                    const char *dir_paths[],
 446                                                    size_t count,
 447                                                    void *user_data);
 448
 449
 450 /**
 451  * @brief Cancels a running scanning task.
 452  *
 453  * @since_tizen 3.0
 454  *
 455  * @remarks It's only for an asynchronous scan function.
 456  *
 457  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 458  *
 459  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 460  *
 461  * @retval #CSR_ERROR_NONE                  Successful
 462  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 463  * @retval #CSR_ERROR_NO_TASK               No task to cancel
 464  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 465  */
 466 int csr_cs_scan_cancel(csr_cs_context_h handle);
 467
 468 //==============================================================================
 469 // Result related
 470 //==============================================================================
 471
 472 /**
 473  * @brief extracts the severity of a detected malware from the detected malware handle.
 474  *
 475  * @since_tizen 3.0
 476  *
 477  * @param[in]  detected    A detected malware handle returned
 478  *                         by csr_cs_result_get_detected_by_idx() or
 479  *                         csr_cs_result_get_detected_most_severe().
 480  * @param[out] pseverity  A pointer of the severity of a detected malware.
 481  *
 482  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 483  *
 484  * @retval #CSR_ERROR_NONE                 Successful
 485  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 486  * @retval #CSR_ERROR_INVALID_PARAMETER    pseverity is invalid.
 487  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 488  */
 489 int csr_cs_detected_get_severity(csr_cs_detected_h detected,
 490                                                                  csr_cs_severity_level_e *pseverity);
 491
 492 /**
 493  * @brief extracts the name of a detected malware from the detected malware handle.
 494  *
 495  * @since_tizen 3.0
 496  *
 497  * @param[in]  detected      A detected malware handle.
 498  * @param[out] malware_name  A pointer of the name of a detected malware. A caller
 499  *                           should not free this string.
 500  *
 501  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 502  *
 503  * @retval #CSR_ERROR_NONE                 Successful
 504  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 505  * @retval #CSR_ERROR_INVALID_PARAMETER    malware_name is invalid
 506  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 507  */
 508 int csr_cs_detected_get_malware_name(csr_cs_detected_h detected,
 509                                                                          const char **pmalware_name);
 510
 511 /**
 512  * @brief extracts an url that contains detailed information on vendor's web site from the detected malware handle.
 513  *
 514  * @since_tizen 3.0
 515  *
 516  * @param[in]  detected      A detected malware handle.
 517  * @param[out] detailed_url  A pointer of an url that contains detailed information on vendor's web site.\n
 518  *                           It can be null if a vendor doesn't provide this information.\n
 519  *                           A caller should not free this string.
 520  *
 521  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 522  *
 523  * @retval #CSR_ERROR_NONE                 Successful
 524  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 525  * @retval #CSR_ERROR_INVALID_PARAMETER    malware_name is invalid.
 526  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 527  */
 528 int csr_cs_detected_get_detailed_url(csr_cs_detected_h detected,
 529                                                                          const char **pdetailed_url);
 530
 531 /**
 532  * @brief extracts the time stamp when a malware is detected from the detected malware handle.
 533  *
 534  * @since_tizen 3.0
 535  *
 536  * @param[in]  detected   A detected malware handle.
 537  * @param[out] timestamp  A pointer of the time stamp in milli second when a malware is detected. A caller should not free this.
 538  *
 539  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 540  *
 541  * @retval #CSR_ERROR_NONE                 Successful
 542  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 543  * @retval #CSR_ERROR_INVALID_PARAMETER    timestamp is invalid
 544  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 545  */
 546 int csr_cs_detected_get_timestamp(csr_cs_detected_h detected,
 547                                                                   time_t *ptimestamp);
 548
 549 /**
 550  * @brief extracts the file name where a malware is detected from the detected malware handle.
 551  *
 552  * @since_tizen 3.0
 553  *
 554  * @param[in]  detected      A detected malware handle.
 555  * @param[out] file_name  A pointer of the file name where a malware is detected. A caller should not free this string. The file name is Null for csr_cs_scan_data.
 556  *
 557  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 558  *
 559  * @retval #CSR_ERROR_NONE                 Successful
 560  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 561  * @retval #CSR_ERROR_INVALID_PARAMETER    file_name is invalid
 562  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 563  */
 564 int csr_cs_detected_get_file_name(csr_cs_detected_h detected,
 565                                                                   const char **pfile_name);
 566
 567 /**
 568  * @brief extracts a user reponse of a popup from the detected malware handle.
 569  *
 570  * @since_tizen 3.0
 571  *
 572  * @param[in]  detected      A detected malware handle.
 573  * @param[out] presponse     A pointer of the user response.
 574  *
 575  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 576  *
 577  * @retval #CSR_ERROR_NONE                 Successful
 578  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 579  * @retval #CSR_ERROR_INVALID_PARAMETER    presponse is invalid
 580  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 581  */
 582 int csr_cs_detected_get_user_response(csr_cs_detected_h detected,
 583                                                                           csr_cs_user_response_e *presponse);
 584
 585 /**
 586  * @brief check if a malware was detected in an application or in a file.
 587  *
 588  * @since_tizen 3.0
 589  *
 590  * @param[in]  detected      A detected malware handle.
 591  * @param[out] pis_app       A pointer of a flag indicating the position a malware was detected.
 592  *
 593  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 594  *
 595  * @retval #CSR_ERROR_NONE                 Successful
 596  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 597  * @retval #CSR_ERROR_INVALID_PARAMETER    pis_app is invalid
 598  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 599  */
 600 int csr_cs_detected_is_app(csr_cs_detected_h detected, bool *pis_app);
 601
 602 /**
 603  * @brief extracts the package id of an application where a malware is detected from detected malware handle.
 604  *
 605  * @since_tizen 3.0
 606  *
 607  * @param[in]  detected      A detected malware handle.
 608  * @param[out] ppkg_id       A pointer of the pakcage id where a malware is detected. A caller should not free this string. This is a null when a malware was not detected in an application.
 609  *
 610  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 611  *
 612  * @retval #CSR_ERROR_NONE                 Successful
 613  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 614  * @retval #CSR_ERROR_INVALID_PARAMETER    ppkg_id is invalid
 615  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 616  */
 617 int csr_cs_detected_get_pkg_id(csr_cs_detected_h detected,
 618                                                            const char **ppkg_id);
 619
 620 /**
 621  * @brief Judges how a detected malware file is handled.
 622  *
 623  * @since_tizen 3.0
 624  * @privlevel platform
 625  * @privilege %http://tizen.org/privilege/antivirus.admin
 626  *
 627  * @remarks  A detected malware may be removed or ignored. When action is
 628  *           #CSR_CS_ACTION_REMOVE, the detected malware file will be removed. If a
 629  *           detected malware is in an application, the application will be removed.
 630  *           Otherwise, only the file will be removed. When a client removes a detected
 631  *           malware with this API, the client must have the privilege to remove it.
 632  *           When action is #CSR_CS_ACTION_IGNORE, the dectected malware file won't be
 633  *           removed. And the ignored file will not treated as malicious. When action is
 634  *           #CSR_CS_ACTION_UNIGNORE, the ignored file will be considered as mailicous
 635  *           again.
 636  *
 637  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 638  * @param[in]  detected   A handle of a detected malware.
 639  * @param[in]  action     An action to be taken.
 640  *
 641  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 642  *
 643  * @retval #CSR_ERROR_NONE                  Successful
 644  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 645  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 646  * @retval #CSR_ERROR_INVALID_PARAMETER     detected or action is invalid
 647  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 648  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File to take action on not found
 649  * @retval #CSR_ERROR_FILE_CHANGED          File to take action on changed after detection
 650  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 651  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 652  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 653  */
 654 int csr_cs_judge_detected_malware(csr_cs_context_h handle,
 655                                                                   csr_cs_detected_h detected, csr_cs_action_e action);
 656
 657
 658 /**
 659  * @brief Gets information on a detected malware file specified by file path.
 660  *
 661  * @since_tizen 3.0
 662  * @privlevel partner
 663  * @privilege %http://tizen.org/privilege/antivirus.scan
 664  *
 665  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 666  * @param[in]  file_path  A path of a detected malware file.
 667  * @param[out] pdetected  A pointer of the detected malware handle. It can be null when
 668  *                        no malware file.
 669  *
 670  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 671  *
 672  * @retval #CSR_ERROR_NONE                  Successful
 673  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 674  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 675  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or action is invalid
 676  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No malware file
 677  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 678  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 679  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 680  */
 681 int csr_cs_get_detected_malware(csr_cs_context_h handle, const char *file_path,
 682                                                                 csr_cs_detected_h *pdetected);
 683
 684 /**
 685  * @brief Gets information on a detected malware files specified by directory path.
 686  *
 687  * @since_tizen 3.0
 688  * @privlevel partner
 689  * @privilege %http://tizen.org/privilege/antivirus.scan
 690  *
 691  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 692  * @param[in]  dir_paths  A directory path where detected malware files exists.
 693  * @param[in]  count      Count of array element of @a dir_paths
 694  * @param[out] plist      A pointer of the detected malware list handle. It can be null
 695  *                        when no malware file.
 696  * @param[out] pcount     Count of detected malware files which existed in the specified
 697  *                        directory.
 698  *
 699  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 700  *
 701  * @retval #CSR_ERROR_NONE                  Successful
 702  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 703  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 704  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or action is invalid
 705  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No malware file
 706  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 707  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 708  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 709  */
 710 int csr_cs_get_detected_malwares(csr_cs_context_h handle,
 711                                                                  const char *dir_paths[], size_t count,
 712                                                                  csr_cs_detected_list_h *plist, size_t *pcount);
 713
 714 /**
 715  * @brief Gets information on a ignored malware file specified by file path.
 716  *
 717  * @since_tizen 3.0
 718  * @privlevel partner
 719  * @privilege %http://tizen.org/privilege/antivirus.scan
 720  *
 721  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 722  * @param[in]  file_path  A path of a ignored malware file.
 723  * @param[out] pdetected  A pointer of the detected malware handle. It can be null when
 724  *                        no ignored file.
 725  *
 726  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 727  *
 728  * @retval #CSR_ERROR_NONE                  Successful
 729  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 730  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 731  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or action is invalid
 732  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No ignored file
 733  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 734  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 735  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 736  */
 737 int csr_cs_get_ignored_malware(csr_cs_context_h handle, const char *file_path,
 738                                                            csr_cs_detected_h *pdetected);
 739
 740 /**
 741  * @brief Gets information on a ignored malware files specified by directory path.
 742  *
 743  * @since_tizen 3.0
 744  * @privlevel partner
 745  * @privilege %http://tizen.org/privilege/antivirus.scan
 746  *
 747  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 748  * @param[in]  dir_paths  A directory path where ignored malware files exists.
 749  * @param[in]  count      Count of array element of @a dir_paths
 750  * @param[out] plist      A pointer of the detected malware list handle. It can be null
 751  *                        when no ignored file.
 752  * @param[out] pcount     Count of ignored malware files which existed in the specified
 753  *                        directory.
 754  *
 755  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 756  *
 757  * @retval #CSR_ERROR_NONE                  Successful
 758  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 759  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 760  * @retval #CSR_ERROR_INVALID_PARAMETER     file_path or action is invalid
 761  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No ingored file
 762  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 763  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 764  * @retval #CSR_ERROR_UNKNOWN               Error with unknown reason
 765  */
 766 int csr_cs_get_ignored_malwares(csr_cs_context_h handle,
 767                                                                 const char *dir_paths[], size_t count,
 768                                                                 csr_cs_detected_list_h *plist, size_t *pcount);
 769
 770 /**
 771  * @brief Extracts the detected malware handle from the detected malware list handle.
 772  *
 773  * @since_tizen 3.0
 774  *
 775  * @param[in]  list        A detected malware list handle returned by
 776  *                         csr_cs_get_detected_malwares() or
 777  *                         csr_cs_get_ignored_malwares().
 778  * @param[in]  index       An index of a target detected malware handle to get.
 779  * @param[out] pdetected   A pointer of the detected malware handle. It can be null when
 780  *                         index is invalid.
 781  *
 782  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 783  *
 784  * @retval #CSR_ERROR_NONE                 Successful
 785  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid list
 786  * @retval #CSR_ERROR_INVALID_PARAMETER    index or pdetected is invalid.
 787  * @retval #CSR_ERROR_UNKNOWN              Error with unknown reason
 788  */
 789 int csr_cs_dlist_get_detected(csr_cs_detected_list_h list, size_t index,
 790                                                           csr_cs_detected_h *pdetected);
 791
 792 #ifdef __cplusplus
 793 }
 794 #endif
 795
 796 #endif