So that you can also 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.
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 have been filled with a message appropriate for the error situation.
· Generate Scanner Instance (GET_INSTANCE)
This static method generates an instance of the virus scan interface, which is based on a given virus scan profile.
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 that is to be used.
If you leave the field empty, the default profile is used. You should only do this in application programs for test purposes and in justified exceptional cases.
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 as follows to this exception:
§ 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, and this exception must therefore always be reported.
INTERNAL_ERROR
An unexpected error 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
Wrong name of the configuration parameter or the parameter is not permitted in this context.
WRONG_VALUE_SYNTAX
The value is not permitted for this type of parameter.
· Perform Virus Scan (SCAN_FILE)
The virus scan is performed with this method.
¡ Parameters
IF_JOB_ID
This parameter can be freely specified by the calling application. It can, for example, 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 has no influence on the evaluation 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 has no influence on the evaluation of the method call.
ET_INFECTION
Information about infections found is transferred using this table parameter.
The content of this table has no influence on the evaluation of the method call.
¡ Exceptions
NOT_AVAILABLE
The instance is temporarily unavailable. This exception is triggered if events that mean that the scanner is not available (such as an update of the virus signatures) occur between the generation of the instance and the performance of a scan request.
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
This parameter can be freely specified by the calling application. It can, for example, 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 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.
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 has no influence on the evaluation 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 has no influence on the evaluation of the method call.
ET_INFECTION
Information about infections found is transferred using this table parameter.
The content of this table has no influence on the evaluation of the method call.
¡ Exceptions
NOT_AVAILABLE
The instance is temporarily unavailable. This exception is triggered if events that mean that the scanner is not available (such as an update of the virus signatures) occur between the generation of the instance and the performance of a scan request.
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 checked.
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.
· Get Error Text (GET_SCANRC_TEXT)
Returns a short explanatory text for a return code of the scanner (constants CON_SCANRC_...).
¡ Parameters
IF_SCANRC
The error code of the scanner.
EF_TEXT
A string with the explanatory text.
¡ Exceptions
Unknown error codes do not return an exception, but rather a corresponding text.
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.