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