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