Integrating the Virus Scan Interface into Customer Developments

Use

To allow you to integrate the virus scan interface into applications that you develop yourself, its class CL_VSI is described below.

The naming convention / <Name of the package>/ <Name of the function> applies for the virus scan profiles delivered by SAP. The Active indicator is not set for these virus scan profiles; on the other hand, the Use Reference Profile indicator is set, although the field Reference Profile remains empty.

Description of the Class CL_VSI of the Virus Scan Interface

The class CL_VSI provides methods that are required for the implementation of a virus scan.

All triggered exceptions are assigned an ABAP message; that is, the SY fields are filled with an appropriate message for the error situation.

Generate Scanner Instance ( GET_INSTANCE)

You can use this static method to generate an instance of the virus scan interface, which is based on a specified virus scan profile.

In this way, you can generate the scanner instance once for each program and then use the obtained scanner repeatedly. The load balancing between different virus scan servers in the same scanner group is performed only during the execution of a virus scan.
- Parameters
  
  IF_PROFILE
  
  The name of the virus scan profile to be used.
  
  If you leave this field empty, the default profile is used. You should only do this in application programs for test purposes and in justified exceptional situations.
  
  EO_INSTANCE
  
  The generated instance that can be used for scanning.
- Exceptions
  
  PROFILE_NOT_ACTIVE
  
  This exception is triggered if the Active indicator is not set in Customizing for the specified virus scan profile. This means that the system administrator does not want a virus scan for this virus scan profile.
  
  The application must react to this exception as follows:
  - If the virus scan is an optional function of the application, this exception must be ignored and the application function can be performed.
  - If the virus scan is a mandatory function of the application, this exception must be reported to the user and the application function must not be performed.
    
    CONFIGURATION_ERROR
    
    There is a configuration error in the Customizing of the virus scan interface. This error must always be corrected. This exception should therefore always be reported.
    
    INTERNAL_ERROR
    
    An unforeseen error has occurred.
Set Scan Parameters ( SET_PARAMETER)

You can use this method to set scan parameters for the scan instance. These are transferred to the scanner for all subsequent scan requests. You can also set local scan parameters for each scan request.

If a profile consists of multiple steps, the parameters set here are transferred to every step and may overwrite data entered in the scanner group there.
- Parameters
  
  IF_KEY: The name of the configuration parameter. You can only set configuration parameters delivered by SAP (table VSCAN_PARAM).
  
  IF_VALUE: The value to be set.
- Exceptions
  
  WRONG_KEY
  
  Incorrect name of the configuration parameter, or the parameter is not permitted in this context.
  
  WRONG_VALUE_SYNTAX
  
  The value is not permitted for this parameter type.
Perform Virus Scan ( SCAN_FILE)

The virus scan is performed with this method.
- Parameters
  
  IF_JOB_ID
  
  The calling application can assign this parameter in any way. For example, it can be used to specify the object to be checked (file name) or to allow unique identification.
  
  If you leave this field empty, the scan engine transfers the name of the virus scan profile used.
  
  IF_FILENAME
  
  File name of the local file to be scanned. The file must exist locally on the application server.
  
  IF_DO_CLEAN
  
  If this parameter has the value ABAP_TRUE, a cleanup is to be performed. If no infection is found or the cleanup was successful (return value of EF_SCANRC is either CL_VSI=>CON_SCANRC_OK or CL_VSI=>CON_SCANRC_CLEAN_OK), the result is made available using the parameter EF_DATA.
  
  If the parameter has the value ABAP_FALSE, only a check is to be performed.
  
  IT_SCAN_PARAMETER
  
  A table of scan parameters. The evaluation of the scan parameters is left to the scan engine. If you are using a profile with multiple steps, these parameters are transferred to each step.
  
  EF_SCANRC
  
  The result of the check or cleanup. You can use the constants CON_SCANRC_... from the interface IF_VSCAN_INSTANCE for error situations that occur frequently.
  
  The return values CON_SCANRC_OK and CON_SCANRC_CLEAN_OK are regarded as success, all other values as failure. There is also the return value CON_SCANRC_NOT_SCANNED, which outputs a warning.
  
  ET_BAPIRET
  
  ABAP messages are transferred using this table parameter.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_SCANERROR
  
  Information about scan errors is transferred using this table parameter. There is a scan error, for example, if the transferred file is a password-protected archive, which the scan engine therefore cannot check.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_INFECTION
  
  Information about infections found is transferred using this table parameter.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_CONTENTINFO
  
  Information about the scanned file is transferred using this table parameter. The MIME type is in the component CONTENT_TYPE.
  
  The parameter is only filled if you have activated the MIME type check in the virus scan application (profile configuration parameter CUST_CHECK_MIME_TYPE).
- Exceptions
  
  NOT_AVAILABLE
  
  The instance is temporarily not available. This exception is triggered if events occur between the generation of the instance and the performance of a scan request that mean that the scanner is not available (such as an update of the virus signatures).
  
  CONFIGURATION_ERROR
  
  There is a configuration error. This exception is triggered if the scan cannot be performed not due to the inbound data, but rather due to the configuration settings.
  
  INTERNAL_ERROR
  
  This exception is triggered in other exception situations.
  
  DIFFERENT_HOSTS
  
  Virus scan server and application server are different.
Perform Virus Scan ( SCAN_BYTES)

The virus scan is performed with this method.
- Parameters
  
  IF_JOB_ID
  
  The calling application can assign this parameter in any way. For example, it can be used to specify the object to be checked (file name) or to allow unique identification.
  
  If you leave this field empty, the scan engine transfers the name of the virus scan profile used.
  
  IF_DATA
  
  The byte sequence to be checked.
  
  IF_DO_CLEAN
  
  If this parameter has the value ABAP_TRUE, a cleanup should be performed. If no infection is found or the cleanup was successful (return value of EF_SCANRC is either CL_VSI=>CON_SCANRC_OK or CL_VSI=>CON_SCANRC_CLEAN_OK), the result is made available using the parameter EF_DATA.
  
  If the parameter has the value ABAP_FALSE, only a check is to be performed.
  
  IT_SCAN_PARAMETER
  
  A table of scan parameters. The evaluation of the scan parameters is left to the scan engine. If you are using a profile with multiple steps, these parameters are transferred to each step.
  
  EF_SCANRC
  
  The result of the check or cleanup. You can use the constants CON_SCANRC_... from the interface IF_VSCAN_INSTANCE for error situations that occur frequently.
  
  The return values CON_SCANRC_OK and CON_SCANRC_CLEAN_OK are regarded as success, all other values as failure. There is also the return value CON_SCANRC_NOT_SCANNED, which outputs a warning.
  
  EF_DATA
  
  If IF_DO_CLEAN has the value ABAP_TRUE and the cleanup was successful ( EF_SCANRC = CON_SCANRC_CLEAN_OK), the cleaned byte sequence is returned using this parameter.
  
  ET_BAPIRET
  
  ABAP messages are transferred using this table parameter.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_SCANERROR
  
  Information about scan errors is transferred using this table parameter. There is a scan error, for example, if the transferred file is a password-protected archive, which the scan engine therefore cannot check.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_INFECTION
  
  Information about infections found is transferred using this table parameter.
  
  The content of this table does not have any effect on the valuation of the method call.
  
  ET_CONTENTINFO
  
  Information about the scanned file is transferred using this table parameter. The MIME type is in the component CONTENT_TYPE.
  
  The parameter is only filled if you have activated the MIME type check in the virus scan application (profile configuration parameter CUST_CHECK_MIME_TYPE).
- Exceptions
  
  NOT_AVAILABLE
  
  The instance is temporarily not available. This exception is triggered if events occur between the generation of the instance and the performance of a scan request that mean that the scanner is not available (such as an update of the virus signatures).
  
  CONFIGURATION_ERROR
  
  There is a configuration error. This exception is triggered if the scan cannot be performed not due to the inbound data, but rather due to the configuration settings.
  
  INTERNAL_ERROR
  
  This exception is triggered in other exception situations.
Perform Virus Scan ( SCAN_ITAB)

The virus scan is performed with this method.

The meanings of the parameters are documented for the method SCAN_BYTES. The data to be checked is transferred using the parameter IT_ITAB.

The internal table must fulfill the following conditions:
- It is a STANDARD or SORTED table.
- The row type of the table is either flat of type X or C, or a structure with exactly one field of type X or C.
You can optionally specify the total length of the data (for X tables in bytes, for C tables in characters) using the parameter IF_DATALENGTH (this is only meaningful for X tables for the reasons explained below). If the parameter is not filled, the entire data object is examined.

The content of C tables is first concatenated by rows into a character string, where concluding spaces in the individual table rows are removed, in accordance with ABAP semantics. The length restriction (see above) is applied to this character string, and the result is converted to UTF-8 format. This value is transferred to the scanner.
Determine error text ( GET_SCANRC_TEXT)

Returns a short explanatory text for a scanner return code (constants CON_SCANRC_...).
- Parameters
  
  IF_SCANRC
  
  The scanner error code.
  
  EF_TEXT
  
  A string containing the explanatory text.
- Exceptions
  
  Unknown error codes do not return exceptions, but rather a corresponding text.
  
  Note
  
  If the function that you have developed is a standard function that can be used by other developer groups, you should allow in your interface the possibility for callers to assign a profile name. Only if this was not transferred should you use the name of your own virus scan profile.
  
  This ensures that not all users of your function are processed using the same virus scan profile, meaning that the separate activation and deactivation of the virus scan remains possible.