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       Content screening to detect malware in files
  21  */
  22 #ifndef __CSR_CONTENT_SCREENING_API_H_
  23 #define __CSR_CONTENT_SCREENING_API_H_
  24
  25 #include <time.h>
  26 #include <stddef.h>
  27
  28 #include <csr-content-screening-types.h>
  29 #include <csr-error.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * @addtogroup CAPI_CSR_FRAMEWORK_CS_MODULE
  37  * @{
  38  */
  39
  40
  41 /**
  42  * @brief Initializes and returns a Content Screening API handle.
  43  *
  44  * @details A Content Screening API handle (or CSR CS handle) is obtained by this method.
  45  *          The handle is required for subsequent CSR CS API calls.
  46  *
  47  * @since_tizen 3.0
  48  *
  49  * @remarks The @a handle should be released using csr_cs_context_destroy().
  50  * @remarks Multiple handles can be obtained.
  51  *
  52  * @param[out] handle A pointer of CSR CS context handle.
  53  *
  54  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  55  *
  56  * @retval #CSR_ERROR_NONE                  Successful
  57  * @retval #CSR_ERROR_INVALID_HANDLE        @a handle may be null
  58  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
  59  * @retval #CSR_ERROR_SYSTEM                System error
  60  *
  61  * @see csr_cs_context_destroy()
  62  */
  63 int csr_cs_context_create(csr_cs_context_h *handle);
  64
  65 /**
  66  * @brief Releases all system resources associated with a Content Screening API handle.
  67  *
  68  * @since_tizen 3.0
  69  *
  70  * @param[in] handle CSR CS context handle returned by csr_cs_context_create().
  71  *
  72  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
  73  *
  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_SYSTEM                System error
  78  *
  79  * @see csr_cs_context_create()
  80  */
  81 int csr_cs_context_destroy(csr_cs_context_h handle);
  82
  83 /**
  84  * @brief Sets a popup option for malware detected.
  85  *
  86  * @details If #CSR_CS_ASK_USER is set, a popup will be prompted to a user when a malware
  87  *          is detected. If #CSR_CS_NOT_ASK_USER is set which is default value, no popup
  88  *          will be prompted even if a malware is detected. User can allow, disallow and
  89  *          remove detected malware by popup. Selection can be different between malware's
  90  *          severity.
  91  *
  92  * @since_tizen 3.0
  93  *
  94  * @remarks This option is disabled(#CSR_CS_NOT_ASK_USER) as a default.
  95  *
  96  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
  97  * @param[in] ask_user  Popup option to set or unset.
  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_cs_context_create()
 107  * @see csr_cs_context_destroy()
 108  */
 109 int csr_cs_set_ask_user(csr_cs_context_h handle, csr_cs_ask_user_e ask_user);
 110
 111 /**
 112  * @brief Sets a popup message of a client in case that a malware is detected.
 113  *
 114  * @details Default message is "Malware 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_cs_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 CS context handle returned by csr_cs_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_cs_context_create()
 134  * @see csr_cs_context_destroy()
 135  */
 136 int csr_cs_set_popup_message(csr_cs_context_h handle, const char *message);
 137
 138 /**
 139  * @brief Sets a maximum core usage during scanning.
 140  *
 141  * @since_tizen 3.0
 142  *
 143  * @remarks If a core usage is not set, #CSR_CS_USE_CORE_DEFAULT will be used.
 144  *
 145  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 146  * @param[in] usage     A maximum core usage during scanning.
 147  *
 148  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 149  *
 150  * @retval #CSR_ERROR_NONE                  Successful
 151  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 152  * @retval #CSR_ERROR_INVALID_PARAMETER     @a usage is invalid
 153  * @retval #CSR_ERROR_SYSTEM                System error
 154  *
 155  * @see csr_cs_context_create()
 156  * @see csr_cs_context_destroy()
 157  */
 158 int csr_cs_set_core_usage(csr_cs_context_h handle, csr_cs_core_usage_e usage);
 159
 160 /**
 161  * @brief Sets a scan on cloud option.
 162  *
 163  * @since_tizen 3.0
 164  *
 165  * @remarks If an engine does not support "scanning on cloud", this option is silently
 166  *          ignored.
 167  *
 168  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 169  *
 170  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 171  *
 172  * @retval #CSR_ERROR_NONE                  Successful
 173  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 174  * @retval #CSR_ERROR_SYSTEM                System error
 175  *
 176  * @see csr_cs_context_create()
 177  * @see csr_cs_context_destroy()
 178  */
 179 int csr_cs_set_scan_on_cloud(csr_cs_context_h handle);
 180
 181 /**
 182  * @brief Scans a data buffer for malware.
 183  *
 184  * @details @a malware result of this method is not available for being judged by
 185  *          csr_cs_judge_detected_malware() because it's data, not file, so cannot being
 186  *          removed or ignored.
 187  *
 188  * @since_tizen 3.0
 189  * @privlevel partner
 190  * @privilege %http://tizen.org/privilege/antivirus.scan
 191  *
 192  * @remarks Scan data synchronously.
 193  * @remarks The @a malware will be released when @a handle is released using
 194  *          csr_cs_context_destroy().
 195  *
 196  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 197  * @param[in]  data       A scan target data.
 198  * @param[in]  length     A size of a scan target data.
 199  * @param[out] malware    A pointer of the detected malware handle. It can be null when
 200  *                        no malware detected.
 201  *
 202  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 203  *
 204  * @retval #CSR_ERROR_NONE                  Successful
 205  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 206  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 207  * @retval #CSR_ERROR_INVALID_PARAMETER     @a data or @a malware is invalid
 208  * @retval #CSR_ERROR_PERMISSION_DENIED     No privilege to call
 209  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 210  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 211  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 212  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 213  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 214  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 215  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 216  * @retval #CSR_ERROR_SYSTEM                System error
 217  *
 218  * @see csr_cs_context_create()
 219  * @see csr_cs_context_destroy()
 220  */
 221 int csr_cs_scan_data(csr_cs_context_h handle, const unsigned char *data, size_t length,
 222                                          csr_cs_malware_h *malware);
 223
 224 /**
 225  * @brief Scans a file specified by file path for malware.
 226  *
 227  * @since_tizen 3.0
 228  * @privlevel partner
 229  * @privilege %http://tizen.org/privilege/antivirus.scan
 230  *
 231  * @remarks  Scan file synchronously.
 232  * @remarks  The @a malware will be released when @a handle is released using
 233  *           csr_cs_context_destroy().
 234  *
 235  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 236  * @param[in]  file_path  A path of scan target file.
 237  * @param[out] malware    A pointer of the detected malware handle. It can be null when
 238  *                        no malware detected.
 239  *
 240  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 241  *
 242  * @retval #CSR_ERROR_NONE                  Successful
 243  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 244  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 245  * @retval #CSR_ERROR_INVALID_PARAMETER     @a file_path or @a malware is invalid
 246  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 247  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 248  * @retval #CSR_ERROR_DB                    DB transaction error
 249  * @retval #CSR_ERROR_REMOVE_FAILED         File remove failed when malware exist and
 250  *                                          user select to remove by popup. @a malware
 251  *                                          will be allocated on this error unlike others.
 252  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 253  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 254  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 255  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 256  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 257  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 258  * @retval #CSR_ERROR_ENGINE_PERMISSION     Insufficient permission of engine
 259  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 260  * @retval #CSR_ERROR_SYSTEM                System error
 261  *
 262  * @see csr_cs_context_create()
 263  * @see csr_cs_context_destroy()
 264  */
 265 int csr_cs_scan_file(csr_cs_context_h handle, const char *file_path,
 266                                          csr_cs_malware_h *malware);
 267
 268 /**
 269  * @brief Sets a callback function for the case that a file scan is completed.
 270  *
 271  * @since_tizen 3.0
 272  *
 273  * @remarks Callback for asynchronous scan functions.
 274  *
 275  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 276  * @param[in] callback  A callback function for each file or application scanning
 277  *                      done without any malware.
 278  *
 279  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 280  *
 281  * @retval #CSR_ERROR_NONE                  Successful
 282  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 283  * @retval #CSR_ERROR_INVALID_PARAMETER     @a callback is invalid
 284  * @retval #CSR_ERROR_SYSTEM                System error
 285  *
 286  * @see csr_cs_scan_files_async()
 287  * @see csr_cs_scan_dir_async()
 288  * @see csr_cs_scan_dirs_async()
 289  */
 290 int csr_cs_set_file_scanned_cb(csr_cs_context_h handle, csr_cs_file_scanned_cb callback);
 291
 292 /**
 293  * @brief Sets a callback function for detection of a malware.
 294  *
 295  * @since_tizen 3.0
 296  *
 297  * @remarks Callback for asynchronous scan functions.
 298  *
 299  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 300  * @param[in] callback  A callback function for each file or application scanning done
 301  *                      with malware detected.
 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     @a callback is invalid
 308  * @retval #CSR_ERROR_SYSTEM                System error
 309  *
 310  * @see csr_cs_scan_files_async()
 311  * @see csr_cs_scan_dir_async()
 312  * @see csr_cs_scan_dirs_async()
 313  */
 314 int csr_cs_set_detected_cb(csr_cs_context_h handle, csr_cs_detected_cb callback);
 315
 316 /**
 317  * @brief Sets a callback function for scanning completed without an error.
 318  *
 319  * @since_tizen 3.0
 320  *
 321  * @remarks Callback for asynchronous scan functions.
 322  *
 323  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 324  * @param[in] callback  A callback function for scanning completed successfully.
 325  *
 326  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 327  *
 328  * @retval #CSR_ERROR_NONE                  Successful
 329  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 330  * @retval #CSR_ERROR_INVALID_PARAMETER     @a callback is invalid
 331  * @retval #CSR_ERROR_SYSTEM                System error
 332  *
 333  * @see csr_cs_scan_files_async()
 334  * @see csr_cs_scan_dir_async()
 335  * @see csr_cs_scan_dirs_async()
 336  */
 337 int csr_cs_set_completed_cb(csr_cs_context_h handle, csr_cs_completed_cb callback);
 338
 339 /**
 340  * @brief Sets a callback function for scanning cancelled.
 341  *
 342  * @since_tizen 3.0
 343  *
 344  * @remarks Callback for asynchronous scan functions.
 345  * @remarks Client can cancel asynchronous scanning by csr_cs_cancel_scanning().
 346  *
 347  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 348  * @param[in] callback  A callback function for scanning cancelled.
 349  *
 350  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 351  *
 352  * @retval #CSR_ERROR_NONE                  Successful
 353  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 354  * @retval #CSR_ERROR_INVALID_PARAMETER     @a callback is invalid
 355  * @retval #CSR_ERROR_SYSTEM                System error
 356  *
 357  * @see csr_cs_scan_files_async()
 358  * @see csr_cs_scan_dir_async()
 359  * @see csr_cs_scan_dirs_async()
 360  * @see csr_cs_cancel_scanning()
 361  */
 362 int csr_cs_set_cancelled_cb(csr_cs_context_h handle, csr_cs_cancelled_cb callback);
 363
 364 /**
 365  * @brief Sets a callback function for scanning stopped with an error.
 366  *
 367  * @since_tizen 3.0
 368  *
 369  * @remarks Callback for asynchronous scan functions.
 370  *
 371  * @param[in] handle    CSR CS context handle returned by csr_cs_context_create().
 372  * @param[in] callback  A callback function for scanning stopped with an error.
 373  *
 374  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 375  *
 376  * @retval #CSR_ERROR_NONE                  Successful
 377  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 378  * @retval #CSR_ERROR_INVALID_PARAMETER     @a callback is invalid
 379  * @retval #CSR_ERROR_SYSTEM                System error
 380  *
 381  * @see csr_cs_scan_files_async()
 382  * @see csr_cs_scan_dir_async()
 383  * @see csr_cs_scan_dirs_async()
 384  */
 385 int csr_cs_set_error_cb(csr_cs_context_h handle, csr_cs_error_cb callback);
 386
 387 /**
 388  * @brief Scan files specified by an array of file paths for malware.
 389  *
 390  * @details If scanning of the single file is done without detected malware,
 391  *          csr_cs_file_scanned_cb() called and else if malware detected
 392  *          csr_cs_detected_cb() called. If scanning is cancelled by
 393  *          csr_cs_cancel_scanning(), csr_cs_cancelled_cb() called. If scanning is failed
 394  *          with error, csr_cs_error_cb() is called. If scanning is completed without
 395  *          error, csr_cs_completed_cb(). Every callbacks are registered by callback
 396  *          setter methods to @a handle and if callback is not registered, it will just
 397  *          skipped to be called.
 398  *
 399  * @since_tizen 3.0
 400  * @privlevel partner
 401  * @privilege %http://tizen.org/privilege/antivirus.scan
 402  *
 403  * @remarks Asynchronous function.
 404  * @remarks The caller should set callback functions before call this method.
 405  * @remarks Detected malware which is provided to the callback will be released when
 406  *          @a handle is released using csr_cs_context_destroy().
 407  *
 408  * @param[in]  handle       CSR CS context handle returned by csr_cs_context_create().
 409  * @param[in]  file_paths   An array of scan target files.
 410  * @param[in]  count        A number of scan target files.
 411  * @param[in]  user_data    The pointer of a user data. It can be null.
 412  *                          It is delivered back to the client when a callback function
 413  *                          is called.
 414  *
 415  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 416  *
 417  * @retval #CSR_ERROR_NONE                  Successful
 418  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 419  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 420  * @retval #CSR_ERROR_INVALID_PARAMETER     @a file_paths is invalid
 421  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 422  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 423  * @retval #CSR_ERROR_BUSY                  Busy for processing another request
 424  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 425  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 426  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 427  * @retval #CSR_ERROR_DB                    DB transaction error
 428  * @retval #CSR_ERROR_ENGINE_PERMISSION     Insufficient permission of engine
 429  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 430  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 431  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 432  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 433  * @retval #CSR_ERROR_SYSTEM                System error
 434  *
 435  * @pre It is required to set callbacks, csr_cs_completed_cb, csr_cs_error_cb(),
 436  *      csr_cs_cancel_scanning(), csr_cs_detected_cb(), and/or csr_cs_file_scanned_cb().
 437  *
 438  * @see csr_cs_set_file_scanned_cb()
 439  * @see csr_cs_set_detected_cb()
 440  * @see csr_cs_set_completed_cb()
 441  * @see csr_cs_set_cancelled_cb()
 442  * @see csr_cs_set_error_cb()
 443  * @see csr_cs_cancel_scanning()
 444  */
 445 int csr_cs_scan_files_async(csr_cs_context_h handle, const char *file_paths[],
 446                                                         size_t count, void *user_data);
 447
 448 /**
 449  * @brief Scans a directory specified by directory path for malware.
 450  *
 451  * @details If scanning of the single file is done without detected malware,
 452  *          csr_cs_file_scanned_cb() called and else if malware detected
 453  *          csr_cs_detected_cb() called. If scanning is cancelled by
 454  *          csr_cs_cancel_scanning(), csr_cs_cancelled_cb() called. If scanning is failed
 455  *          with error, csr_cs_error_cb() is called. If scanning is completed without
 456  *          error, csr_cs_completed_cb(). Every callbacks are registered by callback
 457  *          setter methods to @a handle and if callback is not registered, it will just
 458  *          skipped to be called.
 459  *
 460  * @since_tizen 3.0
 461  * @privlevel partner
 462  * @privilege %http://tizen.org/privilege/antivirus.scan
 463  *
 464  * @remarks Asynchronous function.
 465  * @remarks The caller should set callback functions before calls this method.
 466  * @remarks Detected malware which is provided to the callback will be released when
 467  *          @a handle is released using csr_cs_context_destroy().
 468  *
 469  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 470  * @param[in]  dir_path   A path of scan target directory.
 471  * @param[in]  user_data  The pointer of a user data. It can be null. It is used on
 472  *                        the callback functions which are registered to @a handle.
 473  *
 474  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 475  *
 476  * @retval #CSR_ERROR_NONE                  Successful
 477  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 478  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 479  * @retval #CSR_ERROR_INVALID_PARAMETER     @a dir_path is invalid
 480  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 481  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 482  * @retval #CSR_ERROR_BUSY                  Busy for processing another request
 483  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 484  * @retval #CSR_ERROR_FILE_SYSTEM           File type is invalid. It should be directory
 485  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 486  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 487  * @retval #CSR_ERROR_DB                    DB transaction error
 488  * @retval #CSR_ERROR_ENGINE_PERMISSION     Insufficient permission of engine
 489  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 490  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 491  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 492  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 493  * @retval #CSR_ERROR_SYSTEM                System error
 494  *
 495  * @pre It is required to set callbacks, csr_cs_completed_cb, csr_cs_error_cb(),
 496  *      csr_cs_cancel_scanning(), csr_cs_detected_cb(), and/or csr_cs_file_scanned_cb().
 497  *
 498  * @see csr_cs_set_file_scanned_cb()
 499  * @see csr_cs_set_detected_cb()
 500  * @see csr_cs_set_completed_cb()
 501  * @see csr_cs_set_cancelled_cb()
 502  * @see csr_cs_set_error_cb()
 503  * @see csr_cs_cancel_scanning()
 504  */
 505 int csr_cs_scan_dir_async(csr_cs_context_h handle, const char *dir_path, void *user_data);
 506
 507 /**
 508  * @brief Scan directories specified by an array of directory paths for malware.
 509  *
 510  * @details If scanning of the single file is done without detected malware,
 511  *          csr_cs_file_scanned_cb() called and else if malware detected
 512  *          csr_cs_detected_cb() called. If scanning is cancelled by
 513  *          csr_cs_cancel_scanning(), csr_cs_cancelled_cb() called. If scanning is failed
 514  *          with error, csr_cs_error_cb() is called. If scanning is completed without
 515  *          error, csr_cs_completed_cb(). Every callbacks are registered by callback
 516  *          setter methods to @a handle and if callback is not registered, it will just
 517  *          skipped to be called.
 518  *
 519  * @since_tizen 3.0
 520  * @privlevel partner
 521  * @privilege %http://tizen.org/privilege/antivirus.scan
 522  *
 523  * @remarks Asynchronous function.
 524  * @remarks The caller should set callback functions before calls this method.
 525  * @remarks Detected malware which is provided to the callback will be released when
 526  *          @a handle is released using csr_cs_context_destroy().
 527  *
 528  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 529  * @param[in]  dir_paths  An array of scan target directories.
 530  * @param[in]  count      A number of scan target directories.
 531  * @param[in]  user_data  The pointer of a user data. It can be null. It is used on
 532  *                        the callback functions which are registered to @a handle.
 533  *
 534  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 535  *
 536  * @retval #CSR_ERROR_NONE                  Successful
 537  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 538  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 539  * @retval #CSR_ERROR_INVALID_PARAMETER     @a dir_paths is invalid
 540  * @retval #CSR_ERROR_PERMISSION_DENIED     Access denied
 541  * @retval #CSR_ERROR_NOT_SUPPORTED         Device needed to run API is not supported
 542  * @retval #CSR_ERROR_BUSY                  Busy for processing another request
 543  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File not found
 544  * @retval #CSR_ERROR_FILE_SYSTEM           File type is invalid. It should be directory
 545  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 546  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 547  * @retval #CSR_ERROR_DB                    DB transaction error
 548  * @retval #CSR_ERROR_ENGINE_PERMISSION     Insufficient permission of engine
 549  * @retval #CSR_ERROR_ENGINE_NOT_EXIST      No engine exists
 550  * @retval #CSR_ERROR_ENGINE_DISABLED       Engine is in disabled state
 551  * @retval #CSR_ERROR_ENGINE_NOT_ACTIVATED  Engine is not activated
 552  * @retval #CSR_ERROR_ENGINE_INTERNAL       Engine Internal error
 553  * @retval #CSR_ERROR_SYSTEM                System error
 554  *
 555  * @pre It is required to set callbacks, csr_cs_completed_cb, csr_cs_error_cb(),
 556  *      csr_cs_cancel_scanning(), csr_cs_detected_cb(), and/or csr_cs_file_scanned_cb().
 557  *
 558  * @see csr_cs_set_file_scanned_cb()
 559  * @see csr_cs_set_detected_cb()
 560  * @see csr_cs_set_completed_cb()
 561  * @see csr_cs_set_cancelled_cb()
 562  * @see csr_cs_set_error_cb()
 563  * @see csr_cs_cancel_scanning()
 564  */
 565 int csr_cs_scan_dirs_async(csr_cs_context_h handle, const char *dir_paths[], size_t count,
 566                                                    void *user_data);
 567
 568
 569 /**
 570  * @brief Cancels a running scanning task, asynchronously.
 571  *
 572  * @since_tizen 3.0
 573  *
 574  * @remarks Only for asynchronous scan functions.
 575  *
 576  * @param[in] handle  CSR CS context handle returned by csr_cs_context_create().
 577  *
 578  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 579  *
 580  * @retval #CSR_ERROR_NONE                  Successful
 581  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 582  * @retval #CSR_ERROR_NO_TASK               No task to cancel
 583  * @retval #CSR_ERROR_SYSTEM                System error
 584  *
 585  * @see csr_cs_scan_files_async()
 586  * @see csr_cs_scan_dir_async()
 587  * @see csr_cs_scan_dirs_async()
 588  */
 589 int csr_cs_cancel_scanning(csr_cs_context_h handle);
 590
 591
 592 /**
 593  * @brief Extracts the severity of a detected malware from the detected malware handle.
 594  *
 595  * @since_tizen 3.0
 596  *
 597  * @param[in]  malware   A detected malware handle returned by csr_cs_scan_data(),
 598  *                       csr_cs_scan_file() or csr_cs_malware_list_get_malware().
 599  * @param[out] severity  A pointer of the severity of a detected malware.
 600  *
 601  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 602  *
 603  * @retval #CSR_ERROR_NONE                 Successful
 604  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 605  * @retval #CSR_ERROR_INVALID_PARAMETER    @a severity is invalid
 606  * @retval #CSR_ERROR_SYSTEM               System error
 607  */
 608 int csr_cs_malware_get_severity(csr_cs_malware_h malware,
 609                                                                 csr_cs_severity_level_e *severity);
 610
 611 /**
 612  * @brief Extracts the name of a detected malware from the detected malware handle.
 613  *
 614  * @since_tizen 3.0
 615  *
 616  * @remarks  The @a name must be released using free().
 617  *
 618  * @param[in]  malware  A detected malware handle.
 619  * @param[out] name     A pointer of the name of a detected malware.
 620  *
 621  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 622  *
 623  * @retval #CSR_ERROR_NONE                 Successful
 624  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 625  * @retval #CSR_ERROR_INVALID_PARAMETER    @a name is invalid
 626  * @retval #CSR_ERROR_SYSTEM               System error
 627  */
 628 int csr_cs_malware_get_name(csr_cs_malware_h malware, char **name);
 629
 630 /**
 631  * @brief Extracts an url that contains detailed information on vendor's web site from
 632  *        the detected malware handle.
 633  *
 634  * @since_tizen 3.0
 635  *
 636  * @remarks  The @a detailed_url must be released using free().
 637  *
 638  * @param[in]  malware       A detected malware handle.
 639  * @param[out] detailed_url  A pointer of an url that contains detailed information on
 640  *                           vendor's web site. It can be null if a vendor doesn't
 641  *                           provide this information.
 642  *
 643  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 644  *
 645  * @retval #CSR_ERROR_NONE                 Successful
 646  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 647  * @retval #CSR_ERROR_INVALID_PARAMETER    @a detailed_url is invalid.
 648  * @retval #CSR_ERROR_SYSTEM               System error
 649  */
 650 int csr_cs_malware_get_detailed_url(csr_cs_malware_h malware, char **detailed_url);
 651
 652 /**
 653  * @brief Extracts the time stamp when a malware is detected from the detected malware
 654  *        handle.
 655  *
 656  * @since_tizen 3.0
 657  *
 658  * @param[in]  malware    A detected malware handle.
 659  * @param[out] timestamp  A pointer of the time stamp in milli second when a malware is
 660  *                        detected.
 661  *
 662  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 663  *
 664  * @retval #CSR_ERROR_NONE                 Successful
 665  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 666  * @retval #CSR_ERROR_INVALID_PARAMETER    @a timestamp is invalid
 667  * @retval #CSR_ERROR_SYSTEM               System error
 668  */
 669 int csr_cs_malware_get_timestamp(csr_cs_malware_h malware, time_t *timestamp);
 670
 671 /**
 672  * @brief Extracts the file name where a malware is detected from the detected malware
 673  *        handle.
 674  *
 675  * @since_tizen 3.0
 676  *
 677  * @remarks The @a file_name must be released using free().
 678  *
 679  * @param[in]  malware    A detected malware handle.
 680  * @param[out] file_name  A pointer of the file name where a malware is detected. The
 681  *                        file name is null for csr_cs_scan_data().
 682  *
 683  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 684  *
 685  * @retval #CSR_ERROR_NONE                 Successful
 686  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 687  * @retval #CSR_ERROR_INVALID_PARAMETER    @a file_name is invalid
 688  * @retval #CSR_ERROR_SYSTEM               System error
 689  */
 690 int csr_cs_malware_get_file_name(csr_cs_malware_h malware, char **file_name);
 691
 692 /**
 693  * @brief Extracts a user response of a popup from the detected malware handle.
 694  *
 695  * @since_tizen 3.0
 696  *
 697  * @param[in]  malware   A detected malware handle.
 698  * @param[out] response  A pointer of the user response.
 699  *
 700  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 701  *
 702  * @retval #CSR_ERROR_NONE                 Successful
 703  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 704  * @retval #CSR_ERROR_INVALID_PARAMETER    @a response is invalid
 705  * @retval #CSR_ERROR_SYSTEM               System error
 706  */
 707 int csr_cs_malware_get_user_response(csr_cs_malware_h malware,
 708                                                                          csr_cs_user_response_e *response);
 709
 710 /**
 711  * @brief Checks if a malware was detected in an application or in a file.
 712  *
 713  * @since_tizen 3.0
 714  *
 715  * @param[in]  malware  A detected malware handle.
 716  * @param[out] is_app   A pointer of a flag indicating the position a malware was detected.
 717  *
 718  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 719  *
 720  * @retval #CSR_ERROR_NONE                 Successful
 721  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid result handle
 722  * @retval #CSR_ERROR_INVALID_PARAMETER    @a is_app is invalid
 723  * @retval #CSR_ERROR_SYSTEM               System error
 724  */
 725 int csr_cs_malware_is_app(csr_cs_malware_h malware, bool *is_app);
 726
 727 /**
 728  * @brief Extracts the package id of an application where a malware is detected from
 729  *        detected malware handle.
 730  *
 731  * @since_tizen 3.0
 732  *
 733  * @remarks  The @a pkg_id must be released using free().
 734  *
 735  * @param[in]  malware  A detected malware handle.
 736  * @param[out] pkg_id   A pointer of the package id where a malware is detected.
 737  *                      It is null when a malware was not detected in an application.
 738  *
 739  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 740  *
 741  * @retval #CSR_ERROR_NONE                 Successful
 742  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid detected malware handle
 743  * @retval #CSR_ERROR_INVALID_PARAMETER    @a pkg_id is invalid
 744  * @retval #CSR_ERROR_SYSTEM               System error
 745  */
 746 int csr_cs_malware_get_pkg_id(csr_cs_malware_h malware, char **pkg_id);
 747
 748 /**
 749  * @brief Judges how a detected malware file is handled.
 750  *
 751  * @details  Detected malware will removed by #CSR_CS_ACTION_REMOVE action. File or
 752  *           application which contains malware will be removed.
 753  *           Detected malware will ignored by #CSR_CS_ACTION_IGNORE action. File or
 754  *           application which contains malware will be ignored and will not be treated
 755  *           as malware until this API called with #CSR_CS_ACTION_UNIGNORE action.
 756  *
 757  * @since_tizen 3.0
 758  * @privlevel platform
 759  * @privilege %http://tizen.org/privilege/antivirus.admin
 760  *
 761  * @remarks Detected malware can be removed or ignored.
 762  *
 763  * @param[in]  handle   CSR CS context handle returned by csr_cs_context_create().
 764  * @param[in]  malware  A handle of a detected malware.
 765  * @param[in]  action   An action to be taken.
 766  *
 767  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 768  *
 769  * @retval #CSR_ERROR_NONE                  Successful
 770  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 771  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 772  * @retval #CSR_ERROR_INVALID_PARAMETER     @a malware or @a action is invalid
 773  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 774  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     File to take action on not found
 775  * @retval #CSR_ERROR_FILE_CHANGED          File to take action on changed after detection
 776  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 777  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 778  * @retval #CSR_ERROR_DB                    DB transaction error
 779  * @retval #CSR_ERROR_SYSTEM                System error
 780  */
 781 int csr_cs_judge_detected_malware(csr_cs_context_h handle, csr_cs_malware_h malware,
 782                                                                   csr_cs_action_e action);
 783
 784
 785 /**
 786  * @brief Gets information on a detected malware file specified by file path.
 787  *
 788  * @since_tizen 3.0
 789  * @privlevel partner
 790  * @privilege %http://tizen.org/privilege/antivirus.scan
 791  *
 792  * @remarks The @a malware will be released when @a handle is destroyed.
 793  * @remarks @a file_path will be null if it's result of csr_cs_scan_data().
 794  *
 795  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 796  * @param[in]  file_path  A path of a detected malware file.
 797  * @param[out] malware    A pointer of the detected malware handle. It can be null when
 798  *                        no malware file.
 799  *
 800  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 801  *
 802  * @retval #CSR_ERROR_NONE                  Successful
 803  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 804  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 805  * @retval #CSR_ERROR_INVALID_PARAMETER     @a file_path or @a malware is invalid
 806  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 807  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No malware file
 808  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 809  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 810  * @retval #CSR_ERROR_DB                    DB transaction error
 811  * @retval #CSR_ERROR_SYSTEM                System error
 812  *
 813  * @see csr_cs_scan_data()
 814  * @see csr_cs_scan_file()
 815  * @see csr_cs_detected_cb
 816  */
 817 int csr_cs_get_detected_malware(csr_cs_context_h handle, const char *file_path,
 818                                                                 csr_cs_malware_h *malware);
 819
 820 /**
 821  * @brief Gets information on a detected malware files specified by directory path.
 822  *
 823  * @since_tizen 3.0
 824  * @privlevel partner
 825  * @privilege %http://tizen.org/privilege/antivirus.scan
 826  *
 827  * @remarks  The @a list will be released when @a handle is destroyed.
 828  *
 829  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 830  * @param[in]  dir_paths  A directory path where detected malware files exists.
 831  * @param[in]  count      Count of array element of @a dir_paths
 832  * @param[out] list       A pointer of the detected malware list handle. It can be null
 833  *                        when no malware file.
 834  * @param[out] list_count Count of detected malware files which existed in the specified
 835  *                        directory.
 836  *
 837  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 838  *
 839  * @retval #CSR_ERROR_NONE                  Successful
 840  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 841  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 842  * @retval #CSR_ERROR_INVALID_PARAMETER     @a dir_paths, @a list, or @a count is invalid
 843  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 844  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No malware file
 845  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 846  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 847  * @retval #CSR_ERROR_DB                    DB transaction error
 848  * @retval #CSR_ERROR_SYSTEM                System error
 849  */
 850 int csr_cs_get_detected_malwares(csr_cs_context_h handle, const char *dir_paths[],
 851                                                                  size_t count, csr_cs_malware_list_h *list,
 852                                                                  size_t *list_count);
 853
 854 /**
 855  * @brief Gets information on a ignored malware file specified by file path.
 856  *
 857  * @since_tizen 3.0
 858  * @privlevel partner
 859  * @privilege %http://tizen.org/privilege/antivirus.scan
 860  *
 861  * @remarks  The @a malware will be released when @a handle is destroyed.
 862  *
 863  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 864  * @param[in]  file_path  A path of a ignored malware file.
 865  * @param[out] malware    A pointer of the detected malware handle. It can be null when
 866  *                        no ignored file.
 867  *
 868  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 869  *
 870  * @retval #CSR_ERROR_NONE                  Successful
 871  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 872  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 873  * @retval #CSR_ERROR_INVALID_PARAMETER     @a file_path or @a malware is invalid
 874  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 875  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No ignored file
 876  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 877  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 878  * @retval #CSR_ERROR_DB                    DB transaction error
 879  * @retval #CSR_ERROR_SYSTEM                System error
 880  */
 881 int csr_cs_get_ignored_malware(csr_cs_context_h handle, const char *file_path,
 882                                                            csr_cs_malware_h *malware);
 883
 884 /**
 885  * @brief Gets information on a ignored malware files specified by directory path.
 886  *
 887  * @since_tizen 3.0
 888  * @privlevel partner
 889  * @privilege %http://tizen.org/privilege/antivirus.scan
 890  *
 891  * @remarks  The @a list will be released when @a handle is destroyed.
 892  *
 893  * @param[in]  handle     CSR CS context handle returned by csr_cs_context_create().
 894  * @param[in]  dir_paths  A directory path where ignored malware files exists.
 895  * @param[in]  count      Count of array element of @a dir_paths
 896  * @param[out] list       A pointer of the detected malware list handle. It can be null
 897  *                        when no ignored file.
 898  * @param[out] list_count Count of ignored malware files which existed in the specified
 899  *                        directory.
 900  *
 901  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 902  *
 903  * @retval #CSR_ERROR_NONE                  Successful
 904  * @retval #CSR_ERROR_INVALID_HANDLE        Invalid handle
 905  * @retval #CSR_ERROR_OUT_OF_MEMORY         Not enough memory
 906  * @retval #CSR_ERROR_INVALID_PARAMETER     @a dir_paths, @a list, or @a count is invalid
 907  * @retval #CSR_ERROR_PERMISSION_DENIED     No permission to remove
 908  * @retval #CSR_ERROR_FILE_DO_NOT_EXIST     No ignored file
 909  * @retval #CSR_ERROR_SOCKET                Socket error between client and server
 910  * @retval #CSR_ERROR_SERVER                Server has been failed for some reason
 911  * @retval #CSR_ERROR_DB                    DB transaction error
 912  * @retval #CSR_ERROR_SYSTEM                System error
 913  */
 914 int csr_cs_get_ignored_malwares(csr_cs_context_h handle, const char *dir_paths[],
 915                                                                 size_t count, csr_cs_malware_list_h *list,
 916                                                                 size_t *list_count);
 917
 918 /**
 919  * @brief Extracts the detected malware handle from the detected malware list handle.
 920  *
 921  * @since_tizen 3.0
 922  *
 923  * @param[in]  list     A detected malware list handle returned by
 924  *                      csr_cs_get_detected_malwares() or
 925  *                      csr_cs_get_ignored_malwares().
 926  * @param[in]  index    An index of a target detected malware handle to get.
 927  * @param[out] malware  A pointer of the detected malware handle. It can be null when
 928  *                      index is invalid.
 929  *
 930  * @return #CSR_ERROR_NONE on success, otherwise a negative error value
 931  *
 932  * @retval #CSR_ERROR_NONE                 Successful
 933  * @retval #CSR_ERROR_INVALID_HANDLE       Invalid list
 934  * @retval #CSR_ERROR_INVALID_PARAMETER    @a index or @a malware is invalid.
 935  * @retval #CSR_ERROR_SYSTEM               System error
 936  */
 937 int csr_cs_malware_list_get_malware(csr_cs_malware_list_h list, size_t index,
 938                                                                         csr_cs_malware_h *malware);
 939
 940 /**
 941  * @}
 942  */
 943
 944 #ifdef __cplusplus
 945 }
 946 #endif
 947
 948 #endif