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