Start of Content Area

Background documentation Integrating the Virus Scan Interface into Customer Developments  Locate the document in its SAP Library structure

Use

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.

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 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.

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.

 

 

 

End of Content Area