framework/TCSImpl.h

   1 /*
   2     Copyright (c) 2014, McAfee, Inc.
   3
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without modification,
   7     are permitted provided that the following conditions are met:
   8
   9     Redistributions of source code must retain the above copyright notice, this list
  10     of conditions and the following disclaimer.
  11
  12     Redistributions in binary form must reproduce the above copyright notice, this
  13     list of conditions and the following disclaimer in the documentation and/or other
  14     materials provided with the distribution.
  15
  16     Neither the name of McAfee, Inc. nor the names of its contributors may be used
  17     to endorse or promote products derived from this software without specific prior
  18     written permission.
  19
  20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  21     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23     IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  24     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25     BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  28     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  29     OF THE POSSIBILITY OF SUCH DAMAGE.
  30 */
  31
  32 #ifndef TCSIMPL_H
  33 #define TCSIMPL_H
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40  * \file TCSImpl.h
  41  * \brief TCS Header File
  42  *
  43  * This file provides the Tizen Content Screen API functions.
  44  */
  45 #define TCS_VER_MAX 16
  46
  47 #define TCS_META_MAX 1000
  48
  49 #define TCS_FRAMEWORK_VERSION "2.0.2"
  50
  51 #define TCS_SA_SCANONLY 1 /* Instructs the scan functions to perform scanning only. */
  52
  53 #define TCS_SA_SCANREPAIR 2 /* Instructs the scan functions to carry out both
  54                                                                     scanning and repair/removal of detected malware. */
  55
  56 #define TCS_CB_SCANFINISH 0 /* Informs the caller about completion of async file or data scan. The callback data
  57                                                                             argument pParam is set to point to a TCSScanResult
  58                                                                             structure. if pParam is null then it means Scan did
  59                                                                             not succeed*/
  60
  61 #define TCS_CB_DETECTED 1 /* Informs the caller a malicious code has been
  62                                                               detected in the scan target. The callback data
  63                                                               argument pParam is set to point to a TCSDetected
  64                                                               structure. */
  65
  66 #define TCS_DTYPE_UNKNOWN 0 /* Scan for malicious content in an unknown data
  67                                                                     type. This data type should be used when the
  68                                                                     other types are not appropriate. */
  69
  70 #define TCS_DTYPE_HTML 1 /* Scan for malicious content in HTML. */
  71
  72 #define TCS_VTYPE_PUP 3 /* Potential unwanted program. */
  73
  74 #define TCS_DTYPE_URL 2 /* Scan for URL with malicious content.
  75                                                             url-string format should conform to the
  76                                                             Uniform Resource Locators (RFC 1738)
  77                                                             specification. */
  78
  79 #define TCS_DTYPE_EMAIL 3 /* Scan for email-address with malicious intent.
  80                                                                   email-string format should conform with
  81                                                                   the Internet E-mail address format
  82                                                                   (RFC 822) specification. */
  83
  84 #define TCS_DTYPE_PHONE 4 /* Scan for phone number with malicious intent.
  85                                                               phone-number string consists of the numeric
  86                                                               characters '0' through '9', and the
  87                                                               '#' and '*' characters. */
  88
  89 #define TCS_DTYPE_JAVA 5 /* Scan for malicious Java code. */
  90
  91 #define TCS_DTYPE_JAVAS 6 /* Scan for malicious Java code. */
  92
  93 #define TCS_DTYPE_TEXT 7 /* Scan text data for malicious content. */
  94
  95 #define TCS_VTYPE_MALWARE 1 /* Malware type. */
  96
  97 #define TCS_SC_USER 1 /* Detected malware is harmful to the user. */
  98
  99 #define TCS_SC_TERMINAL 2 /* Detected malware is harmful to the terminal. */
 100
 101 #define TCS_BC_LEVEL0 0 /* Process with a warning. This severity level may
 102                                                           be assigned to data previously considered malicious. */
 103
 104 #define TCS_BC_LEVEL1 1 /* Prompt the user before processing. Ask the user
 105                                                             if they want the application to process the data. */
 106
 107 #define TCS_BC_LEVEL2 2 /* Do not process the data. */
 108
 109 #define TCS_BC_LEVEL3 3 /* Do not process the data and prompt user for removal.
 110                                                         If the content is stored on the terminal,
 111                                                         prompt the user for permission before removal. */
 112
 113 #define TCS_BC_LEVEL4 4 /* Do not process the data and automatically remove if stored. */
 114
 115
 116 /*==================================================================================================
 117                                             MACROS
 118 ==================================================================================================*/
 119
 120 /**
 121  * Helper macro to get error module.
 122  */
 123 #define TCS_ERRMODULE(e) (((e) >> 24) & 0xff)
 124
 125 /**
 126  * Helper macro to get error code.
 127  */
 128 #define TCS_ERRCODE(e) ((e) & 0x00ffffff)
 129
 130 /*==================================================================================================
 131                                  STRUCTURES AND OTHER TYPEDEFS
 132 ==================================================================================================*/
 133 /**
 134  * Structure for version info of TCS Framework and Plugin
 135  */
 136 typedef struct TCSVerInfo_struct
 137 {
 138     char szFrameworkVer[TCS_VER_MAX];
 139     char szPluginVer[TCS_VER_MAX];
 140 } TCSVerInfo;
 141
 142 /**
 143  * Dummy data structure to avoid unexpected data type casting.
 144  */
 145 struct TCSLibHandle_struct {int iDummy;};
 146
 147 /**
 148  * TCS library handle type.
 149  */
 150 typedef struct TCSLibHandle_struct *TCSLIB_HANDLE;
 151
 152 #define INVALID_TCSLIB_HANDLE ((TCSLIB_HANDLE) 0) /* Invalid Content Screening library interface handle. */
 153
 154 /**
 155  * error code type.
 156  */
 157 typedef unsigned long TCSErrorCode;
 158
 159 /**
 160  * Support 64 bits data / file locating
 161  */
 162 typedef long long TCSOffset;
 163
 164 /**
 165  * The calling application specifies scan
 166  * parameters using the TCSScanParam structure. The information
 167  * contained in the structure provides the scan functions with:
 168  * - scan action type (iAction)
 169  * - the scan data type (iDataType)
 170  * - data pointer to the scan target (pPrivate)
 171  * - callback function to retrieve the data size in bytes (pfGetSize)
 172  * - callback function to resize the scan data (pfSetSize)
 173  * - callback function used by the scan functions to retrieve a
 174  *     block of scan data (pfRead)
 175  * - callback function used to write to the scan data (pfWrite)
 176  * - callback function for status/progress reporting (pfCallBack)
 177  */
 178 typedef struct TCSScanParam_struct
 179 {
 180     int iAction; /* The scan-action specifies the type of scanning to be performed on supplied scan data. */
 181
 182     int iDataType; /* The calling application specifies the data type/format of the data to be scanned using this variable. */
 183
 184     int iCompressFlag; /* 0 - decompression disabled, 1 - decompression enabled. */
 185
 186     void *pPrivate; /* Pointer (or handle) to an application object being scanned.
 187                        The scan functions do not perform direct memory I/O using this data
 188                        pointer/handle. The data pointer/handle is simply passed back to the caller when
 189                        performing data read/write using caller specified I/O functions. Also the private
 190                        data is passed back to the caller using the pfCallback function if it is set. */
 191
 192     TCSOffset (*pfGetSize)(void *pPrivate); /* Used by the scan functions
 193                                                to obtain the scan target data size (in bytes) from the caller.
 194
 195                                                This is a synchronous API.
 196                                                [in] pPrivate Pointer (or handle) to an application object being scanned.
 197
 198                                                return - Return Type (int)
 199                                                The size (in bytes) of the data to be scanned.
 200                                                */
 201
 202     int (*pfSetSize)(void *pPrivate, TCSOffset uSize); /* Called by the scan
 203                                                           functions to resize the scanned data to a given size (in bytes) during
 204                                                           repair/clean. The resize function pointer needs to be set if the scan-action
 205                                                           (iAction) is set to TCS_SA_SCANREPAIR.
 206
 207                                                           This is a synchronous API.
 208
 209                                                           @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 210                                                           @param[in] uSize The size (in bytes) of the repaired data.
 211
 212                                                           @return Return Type (int)
 213                                                           The size (in bytes) of the application data.
 214                                                           Not equal to the value of uSize indicating this call fails.
 215                                                           */
 216
 217     unsigned int (*pfRead)(void *pPrivate, TCSOffset uOffset, void *pBuffer,
 218                            unsigned int uCount); /* Used for reading a specified
 219                                                     amount of application data during scanning/analysis.
 220
 221                                                     This is a synchronous API.
 222
 223                                                     @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 224                                                     @param[in] uOffset Read from the offset in the application data.
 225                                                     @param[out] pBuffer The buffer used to store the read data.
 226                                                     @param[in] uCount The size (in bytes) of the data to be read.
 227
 228                                                     @return Return Type (int)
 229                                                     The size (in bytes) of the read data.
 230                                                     Not equal to the value of uCount indicating this call fails.
 231                                                     */
 232
 233     unsigned int (*pfWrite)(void *pPrivate, TCSOffset uOffset, void const *pBuffer,
 234                             unsigned int uCount); /* The scan functions use the
 235                                                      given function to write a specified amount of data to the scanned object as a part
 236                                                      of the repair process. The function pointer needs to be set if the scan action
 237                                                      (iAction) is set to TCS_SA_SCANREPAIR.
 238
 239                                                      This is a synchronous API.
 240
 241                                                      @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 242                                                      @param[in] uOffset Write data from the offset in the application data.
 243                                                      @param[in] pBuffer The buffer hold the data to be written.
 244                                                      @param[in] uCount The size (in bytes) of the data to be written.
 245
 246                                                      @return Return Type (int)
 247                                                      The size (in bytes) of the written data.
 248                                                      Not equal to the value of uCount indicating this call fails.
 249                                                      */
 250
 251     int (*pfCallBack)(void *pPrivate, int iReason, void *pParam); /* This callback
 252                                                                      function is set by the caller to be notified to each detected malware while
 253                                                                      scanning is in process. If specified (not NULL), the scan functions call the
 254                                                                      specified function with the information (e.g. TCS_CB_DETECTED) for each malware
 255                                                                      detected in the content/data during scanning.
 256
 257                                                                      This is a synchronous API.
 258
 259                                                                      @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 260                                                                      @param[in] iReason Reason of this callback.
 261                                                                      @param[in] pParam The data for specified callback reason respectively.
 262
 263                                                                      @return Return Type (int)
 264                                                                      The scanning process continues if the callback function returns 0. If a negative
 265                                                                      value (e.g. -1) is returned, the scanning process is aborted and control is
 266                                                                      returned to the caller.
 267                                                                      */
 268 } TCSScanParam;
 269
 270 /**
 271  * Detected malicious code/content information structure.
 272  */
 273 typedef struct TCSDetected_struct
 274 {
 275     struct TCSDetected_struct *pNext; /* Pointer to next malware found, NULL if at the end of list. */
 276
 277     char const *pszName; /* Detected malware name. */
 278     char const *pszVariant; /* Detected malware's variant name. pszName and
 279                                pszVariant report detected malicious code/content and variant names. The maximum
 280                                string length for both strings is 64 characters and each is terminated by a null
 281                                character ('\\0') - the maximum buffer size for both strings is 65 bytes.
 282
 283                                pszVariant is set to an empty string ("\0") if the detected malware is not a
 284                                variant. */
 285
 286     unsigned int uType; /* Detected malware type. \see TCS_VTYPE_MALWARE */
 287     unsigned int uAction; /* Bit-field specifying severity, class and behavior level.
 288
 289                              Included in the TCSDetected structure is a bit-field variable containing malware
 290                              severity flags and client application behavior levels.
 291
 292                              The scan functions set the TCS_SC_USER flag if the scanned object/data contains
 293                              malware harmful to the user. TCS_SC_TERMINAL flag is set if the malware is
 294                              harmful to the terminal itself. Both TCS_SC_USER and TCS_SC_TERMINAL flags are
 295                              set if the malware is harmful to both the user and the terminal.
 296
 297                              The application behavior level specifies what to do with the data/object
 298                              containing the detected malware.
 299
 300                              When multiple behavior level codes are found in a scanned data/object, the
 301                              calling application would be expected to act with the highest behavior level.
 302                              For example, if both TCS_BC_LEVEL0 and TCS_BC_LEVEL3 were reported, the application
 303                              would need to take on TCS_BC_LEVEL3 action. */
 304
 305     char const *pszFileName; /* Path of the infected file. The pszFileName field
 306                                 report, if not NULL, the complete file path of the infected content. If the scan
 307                                 functions have the ability to scan/analyze inside archives, then the path
 308                                 reported in pszFileName would be composed of multiple paths separated by the '|'
 309                                 character. The first path of the sequence is the real file system path of the
 310                                 currently scanned file, for TCSScanFile(), or empty for TCSScanData(). No
 311                                 assumption should be made on the path name separator used for the archive
 312                                 components of the path (the ones following the first). Only the first component,
 313                                 if not empty, is the real file path of the currently scanned content. */
 314 } TCSDetected;
 315
 316 /**
 317  * Detected malware information is returned to the caller in the TCSScanResult
 318  * structure provided by the caller. The TCSScanResult structure contains a pointer
 319  * to a structure that contains scan result information and a pointer to a function
 320  * used to remove the scan result resource. The memory used to hold the scan result
 321  * is allocated by the scan functions and freed by calling the function pointed by the
 322  * pfFreeResult pointer. The detected malware information includes the malware
 323  * information which had been reported via the callback (pfCallback) function during
 324  * scanning.
 325  *
 326  * \code
 327  * int ScanAppData( ... )
 328  * {
 329  *     TCSScanResult scanResult;
 330  *     .
 331  *     .
 332  *     if (TCSScanData(hScanner, &scanParam, &scanResult) == 0)
 333  *     {
 334  *         .
 335  *         .
 336  *         scanResult.pfFreeResult( &scanResult );
 337  *     }
 338  *     .
 339  *     .
 340  * }
 341  * \endcode
 342  */
 343 typedef struct TCSScanResult_struct
 344 {
 345     int iNumDetected; /* Number of malware found. */
 346     TCSDetected *pDList; /* Detected malware list. */
 347     void (*pfFreeResult)(struct TCSScanResult_struct *pResult); /* Function pointer
 348                                                                    used to free reported scan result.
 349
 350                                                                    This is a synchronous API.
 351                                                                    \param[in] pResult Pointer to data structure in which detected scan result
 352                                                                    information is stored.
 353
 354                                                                    \return None
 355                                                                    */
 356 } TCSScanResult;
 357
 358 /*==================================================================================================
 359                                      FUNCTION PROTOTYPES
 360 ==================================================================================================*/
 361
 362 /**
 363  * \brief Initializes and returns a Tizen Content Screening library
 364  * interface handle.
 365  *
 366  * A Content Screening library interface handle (or TCS library handle) is
 367  * obtained using the TCSLibraryOpen() function. The library handle is required for
 368  * subsequent TCS API calls. The TCSLibraryClose() function releases/closes the library
 369  * handle. Multiple library handles can be obtained using TCSLibraryOpen().
 370  *
 371  * This is a synchronous API.
 372  *
 373  * \return Return Type (TCSLIB_HANDLE) \n
 374  * TCS library interface handle - on success. \n
 375  * INVALID_TCSLIB_HANDLE - on failure. \n
 376  */
 377 TCSLIB_HANDLE TCSLibraryOpen(void);
 378
 379 /**
 380  * \brief Gets the version number of TCS Framework and Plugin.
 381  *
 382  * This is a synchronous API.
 383  *
 384  * \param[in] hLib instance handle obtained from a call to the TCSLibraryOpen().
 385  * \param[out] pVerInfo Pointer to a structure containing version info.
 386  *
 387  * \return Return Type (int) \n
 388  * 0 - on success. \n
 389  * -1 - on failure. \n
 390  */
 391 int TCSGetVersion(TCSLIB_HANDLE hLib, TCSVerInfo *pVerInfo);
 392
 393 /**
 394  * \brief Gets the meta information about the plugin
 395  * \param[in] hLib instance handle obtained from a call to the TCSLibraryOpen().
 396  * \param[out] pszInfo string containing meta info, pszInfo allocated by caller of size TCS_META_MAX.
 397  *
 398  * \return Return Type (int) \n
 399  * 0 - on success. \n
 400  * -1 - on failure. \n
 401  */
 402 int TCSGetInfo(TCSLIB_HANDLE hLib, char *pszInfo);
 403
 404 /**
 405  * \brief Releases system resources associated with an TCS API library
 406  * handle returned by the TCSLibraryOpen() function.
 407  *
 408  * This is a synchronous API.
 409  *
 410  * \param[in] hLib TCS library handle returned by TCSLibraryOpen().
 411  *
 412  * \return Return Type (int) \n
 413  * 0 - on success. \n
 414  * -1 - on failure. \n
 415  */
 416 int TCSLibraryClose(TCSLIB_HANDLE hLib);
 417
 418 /**
 419  * \brief Returns the last error code associated with the given
 420  * TCS library handle.
 421  *
 422  * Once the TCS library handle has been successfully obtained from TCSLibraryOpen(),
 423  * TCSGetLastError() can be used to retrieve the last TCS error that occurred. All TCS
 424  * API functions return zero (= 0) or a valid object pointer if successful, and -1
 425  * or a null object handle (e.g. INVALID_TCSSCAN_HANDLE) in case of an error. The
 426  * TCSGetLastError() function is used to retrieve error information when a TCS
 427  * function fails.
 428  *
 429  * This is a synchronous API.
 430  *
 431  * \param[in] hLib TCS library handle returned by TCSLibraryOpen().
 432  *
 433  * \return Return Type (TCSErrorCode) \n
 434  * Last error code set by the TCS library. The TCSErrorCode data type is defined as a
 435  * 32-bit unsigned integer which contains both component and an error code (see
 436  * Figure about TCS Error Code Format). Two macros are available to extract the error
 437  * module and the error code. Call TCS_ERRMODULE(error-code) to get the error module,
 438  * and TCS_ERRCODE(error-code) to get the error code (where error-code is the value
 439  * returned by TCSGetLastError()).
 440  *
 441  * TCS library call sequence with a call to the TCSGetLastError() function:
 442  *
 443  */
 444 TCSErrorCode TCSGetLastError(TCSLIB_HANDLE hLib);
 445
 446 /**
 447  * \brief TCSScanData() is used to scan a data buffer for malware. The caller
 448  * specifies a scanner action, scan target data type, set I/O functions to access
 449  * the data, and an optional callback function for information retrieval. The result
 450  * of the data scanning is returned in a caller provided data structure.
 451  *
 452  * This is a synchronous API.
 453  *
 454  * \param[in] hLib instance handle obtained from a call to the TCSLibraryOpen()
 455  * function.
 456  * \param[in] pParam Pointer to a structure containing data scan parameters.
 457  * \param[out] pResult Pointer to a structure containing data scan
 458  * results.
 459  *
 460  * \return Return Type (int) \n
 461  * 0 - on success. \n
 462  * -1 - on failure and error code is set. \n
 463  *
 464  */
 465 int TCSScanData(TCSLIB_HANDLE hLib, TCSScanParam *pParam, TCSScanResult *pResult);
 466
 467 /**
 468  * \brief TCSScanDataAsync() is used to scan a data buffer for malware. The caller
 469  * specifies a scanner action, scan target data type, set I/O functions to access
 470  * the data, and a callback function for information retrieval. The result
 471  * of the data scanning is returned to the callback function.
 472  *
 473  * This is a Asynchronous API.
 474  * \param[in] hLib instance handle obtained from a call to the TCSLibraryOpen()
 475  * \param[in] pParam Pointer to a structure containing data scan parameters.
 476  *
 477  * \return Return Type (int) \n
 478  * 0 - on success. \n
 479  * -1 - on failure and error code is set. \n
 480  */
 481 int TCSScanDataAsync(TCSLIB_HANDLE hLib, TCSScanParam *pParam);
 482
 483 /**
 484  * \brief TCSScanFile() is used to scan a file for malware. The caller specifies a
 485  * file name, a scanner action, and scan target data type. The scan result is
 486  * returned in a caller provided data structure.
 487  *
 488  * This is a synchronous API.
 489  *
 490  * \param[in] hLib instance handle obtained from a call to the
 491  * TCSLibraryOpen() function.
 492  * \param[in] pszFileName Name of file to scan. The file name must include the
 493  * absolute path.
 494  * \param[in] iDataType Type of data contained in the file. This is used to
 495  * perform data type specific scans on files.
 496  * \param[in] iAction Type of scanning to perform on file.
 497  * \param[in] iCompressFlag Enables or disables compression.
 498  * \param[out] pResult Pointer to a structure containing data scan results.
 499  *
 500  * \return Return Type (int) \n
 501  * 0 - on success. \n
 502  * -1 - on failure and error code is set. \n
 503  */
 504 int TCSScanFile(TCSLIB_HANDLE hLib, char const *pszFileName, int iDataType,
 505                 int iAction, int iCompressFlag, TCSScanResult *pResult);
 506
 507 /**
 508  * \brief TCSScanFileEx() is used to scan a file for malware. The caller specifies a
 509  * file name, a scanner action, and scan target data type. The scan result is
 510  * returned in a caller provided data structure. Extra parameters pPrivate and
 511  * pfCallBack are for Callback.
 512  *
 513  * This is a synchronous API.
 514  *
 515  * \param[in] hLib instance handle obtained from a call to the
 516  * TCSLibraryOpen() function.
 517  * \param[in] pszFileName Name of file to scan. The file name must include the
 518  * absolute path.
 519  * \param[in] iDataType Type of data contained in the file. This is used to
 520  * perform data type specific scans on files.
 521  * \param[in] iAction Type of scanning to perform on file.
 522  * \param[in] iCompressFlag Enables or disables compression.
 523  * \param[in] pPrivate Pointer (or handle) to an application object being scanned.
 524  * \param[in] pfCallBack Callback function used to notify the report of file scan and also during scan in progress.
 525  * \param[out] pResult Pointer to a structure containing data scan results.
 526  *
 527  * \return Return Type (int) \n
 528  * 0 - on success. \n
 529  * -1 - on failure and error code is set. \n
 530  */
 531 int TCSScanFileEx(TCSLIB_HANDLE hLib, char const *pszFileName, int iDataType,
 532                 int iAction, int iCompressFlag, void *pPrivate,
 533                 int (*pfCallBack)(void *pPrivate, int iReason, void *pParam),
 534                 /* This callback
 535                  function is set by the caller to be notified to each detected malware while
 536                  scanning is in process. If specified (not NULL), the scan functions call the
 537                  specified function with the information (e.g. TCS_CB_DETECTED) for each malware
 538                  detected in the content/data during scanning.
 539
 540                  This is a synchronous API.
 541
 542                  @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 543                  @param[in] iReason Reason of this callback.
 544                  @param[in] pParam The data for specified callback reason respectively.
 545
 546                  @return Return Type (int)
 547                  The scanning process continues if the callback function returns 0. If a negative
 548                  value (e.g. -1) is returned, the scanning process is aborted and control is
 549                  returned to the caller.
 550                  */
 551                 TCSScanResult *pResult);
 552
 553 /**
 554  * \brief TCSScanFileAsync() is used to scan a file for malware. The caller specifies a
 555  * file name, a scanner action, and scan target data type. The scan result is
 556  * returned to the callback function
 557  *
 558  * This is an Asynchronous API.
 559  *
 560  * \param[in] hLib instance handle obtained from a call to the TCSLibraryOpen()
 561  * \param[in] pszFileName Name of file to scan. The file name must include the
 562  * absolute path.
 563  * \param[in] pParam Pointer to a structure containing data scan parameters.
 564  * \param[in] iDataType Type of data contained in the file. This is used to
 565  * perform data type specific scans on files.
 566  * \param[in] iAction Type of scanning to perform on file.
 567  * \param[in] iCompressFlag enables or disables decompression of archive files.
 568  * \param[in] pPrivate Pointer (or handle) to an application object being scanned.
 569  * \param[in] pfCallBack Callback function used to notify the report of file scan and also during scan in progress.
 570  * \return Return Type (int) \n
 571  * 0 - on success. \n
 572  * -1 - on failure and error code is set. \n
 573  */
 574 int TCSScanFileAsync(TCSLIB_HANDLE hLib, char const *pszFileName, int iDataType,
 575                      int iAction, int iCompressFlag, void *pPrivate,
 576                                      int (*pfCallBack)(void *pPrivate, int iReason, void *pParam)
 577                                      /* This callback
 578                                       function is set by the caller to be notified to each detected malware while
 579                                       scanning is in process. If specified (not NULL), the scan functions call the
 580                                       specified function with the information (e.g. TCS_CB_DETECTED) for each malware
 581                                       detected in the content/data during scanning.
 582
 583                                       This is a synchronous API.
 584
 585                                       @param[in] pPrivate Pointer (or handle) to an application object being scanned.
 586                                       @param[in] iReason Reason of this callback.
 587                                       @param[in] pParam The data for specified callback reason respectively.
 588
 589                                       @return Return Type (int)
 590                                       The scanning process continues if the callback function returns 0. If a negative
 591                                       value (e.g. -1) is returned, the scanning process is aborted and control is
 592                                       returned to the caller.
 593                                       */ );
 594
 595 #ifdef __cplusplus
 596 }
 597 #endif
 598
 599 #endif  /* TCSIMPL_H */