com.sap.security.core.server.vsi.api
Interface Instance

All Superinterfaces:

VSIConstants

public interface Instance

extends VSIConstants

Virus scan instance interface.

The scan instance is the main interface for an external user of this API. The service "Virus Scan Provider" returns an instance of either:

• Profile
• Group
• Provider
  • Adapter
  • Server

The layers of this framework are:

    ---------  1
   | Profile |-|-
    ---------   |                                               
                | n -------  1                   1   ---------                
                --<| Group |-|-                 -|--| Server  |  
                    -------   |                 |    ---------
                              | n ----------  1 |        |     
                              --<| Provider |-|-+        |
                                  ----------    |        | 
                                                |    ----+----
                                                -|--| Adapter |
                                                 1   ----+----
                                                         |
                                                         |
                                             ------------+-----------------
                                            | S A P  NW-VSI compatible VSA |
                                            |                              |
                                            | Virus Scan Adapter (VSA)     |
                                            | External Anti Virus Product  |
                                            | from SAP AV partners         |
                                             -----------------------------
  

Remark:
The architecture of the Provider covers either an Adapter or a Server (Virus Scan Server):

• The Virus Scan Server communicates over TCP/IP (SAP RFC protocol) with the JAVA AS (application server) and should only be used for platform or process architecture reasons, e.g. the required OS of SAP NetWeaver and external AV product are different. The server itself uses the virus scan adapter. Thats the reason why there is a link between the Server and the Adapter. The Virus Scan Server is a product of SAP within the SAP NetWeaver suite.
• The virus scan adapter is a native shared library (delivered by an external partner) which can be loaded directly into the JAVA AS process environment. This way ensures a high performace communication with an external virus scaner, because the scan of memory areas are done inplace. The virus scan adapter is also used by the Virus Scan Server and is therefore the single way to the external product.

Eeach running thread must use its own scan instance. The reason for this is the described framework using external (native) shared libraries. There are caching mechanisms in the layer of the Provider, so the time latency of requesting an Instance is very small.

Note:
Please see the example usage of an "Instance" in the Javadoc of VSIService. A requested instance must be released with releaseInstance.

History:

     1.0      Initial Version for SAP NetWeaver 04
     1.1      Added a pattern for clean test.
     1.5      Enhancements in the native VSI layer
     1.6      Dual runtime support (JAVA standalone and J2EE)
	

Since:

1.0

Version:

1.6, $DateTime: 2007/03/20 15:29:56 $

See Also:

Profile, Group, Provider, VSIService, VSIService.getInstance()

Fields inherited from interface com.sap.security.core.server.vsi.api.VSIConstants

TRACE_ERROR, TRACE_INFO, TRACE_MEM_TRACE, TRACE_MEMORY, TRACE_PARAMETERS, TRACE_RFC, TRACE_RFC_TABEL, TRACE_THREAD, TRACE_VIRUS, TRACE_VSA, TRACE_VSA_EVENTS, TRACE_VSI, TRACE_WARNING, VSI_CLEAN_PARAM_NAMES, VSI_CUST_PARAM_NAMES, VSI_E_BAD_EXPRESSION, VSI_E_BUFFER_TOO_SHORT, VSI_E_CBC_TERMINATED, VSI_E_CIO_FAILED, VSI_E_CLEAN_FAILED, VSI_E_CLEAN_OK, VSI_E_CONVERSION_FAILED, VSI_E_DRIVER_FAILED, VSI_E_END_FAILED, VSI_E_EXPIRED, VSI_E_IN_PROGRESS, VSI_E_INVALID_ENUM_INDEX, VSI_E_INVALID_HANDLE, VSI_E_INVALID_PARAM, VSI_E_INVALID_PARAM_TYPE, VSI_E_INVALID_SCANOBJECT, VSI_E_LOAD_FAILED, VSI_E_MACRO_FOUND, VSI_E_NO_SCANINFO, VSI_E_NO_SPACE, VSI_E_NOT_INITIALISED, VSI_E_NOT_SCANNED, VSI_E_NOT_SUPPORTED, VSI_E_NULL_PARAM, VSI_E_OBJPAR_UNSUPPORTED, VSI_E_PARAM_UNSUPPORTED, VSI_E_PATTERN_FOUND, VSI_E_SCAN_FAILED, VSI_E_SCANPAR_UNSUPPORTED, VSI_E_UNKNOWN_ERROR, VSI_E_VIRUS_FOUND, VSI_E_VSA_LOAD_FAILED, VSI_E_XML_CONFIG_FAILED, VSI_INIT_PARAM_NAMES, VSI_OK, VSI_PARAM_TYPES, VSI_SCAN_PARAM_NAMES

Method Summary

boolean	cleanBytes(byte[] byteArray) Scan and clean an array of bytes.
boolean	cleanBytes(byte[] byteArray, long len) Scan and clean the length of an array of bytes.
boolean	cleanBytes(java.lang.String objectName, byte[] byteArray, long len) Scan and clean the length of an array of bytes.
boolean	cleanBytes(java.lang.String objectName, byte[] byteArray, long len, long jobID) Scan and "tries to" clean the infected byte array.
boolean	cleanFile(java.lang.String fileName) Scans and "tries to" clean infected files.
boolean	cleanFile(java.lang.String fileName, long jobID) Scans and "tries to" clean infected files.
long	getCleanedLength()
Infection[]	getInfections() Deprecated. Do not use
long	getJobID()
int	getLastErrorRC() Return the last occured error code.
Parameter	getParameter(java.lang.String paramName) Get parameter from VSA
Parameter[]	getParameters() Get all VSA parameters
ScanError[]	getScanErrors() Deprecated. Do not use
boolean	scanBytes(byte[] byteArray) Scan an array of bytes.
boolean	scanBytes(byte[] byteArray, long len) Scan the length of an array of bytes.
boolean	scanBytes(java.lang.String objectName, byte[] byteArray, long len) Scan the length of an array of bytes.
boolean	scanBytes(java.lang.String objectName, byte[] byteArray, long len, long jobID) "Scan only" for viruses withing a passed byte array.
boolean	scanBytesEx(boolean doClean, byte[] byteArray) Extended Version of scanBytes.
boolean	scanBytesEx(boolean doClean, byte[] byteArray, long len) Extended Version of scanBytes.
boolean	scanBytesEx(boolean doClean, java.lang.String objectName, byte[] byteArray, long len) Extended Version of scanBytes.
boolean	scanBytesEx(boolean doClean, java.lang.String objectName, byte[] byteArray, long len, long jobID) Extended Version of scanBytes.
boolean	scanFile(java.lang.String fileName) "Scans only" for viruses.
boolean	scanFile(java.lang.String fileName, long jobID) "Scans only" for viruses.
boolean	scanFileEx(boolean doClean, java.lang.String fileName) Extended Version of scanFile.
boolean	scanFileEx(boolean doClean, java.lang.String fileName, long jobID) Extended Version of scanFile.
void	setActiveContent(boolean bActiveContent) Deprecated. this method has no effect
boolean	setDefaultConfig() Set or reset the default configuration of a VSA.
void	setJobID(long jobID) Set the JOB identifier.
boolean	setParameter(Parameter vsParameter) Set a parameter
void	setScanInfo(boolean bScanInfo)

Method Detail

scanFile

public boolean scanFile(java.lang.String fileName,
                        long jobID)
                 throws VSIServiceException,
                        VirusScanException,
                        VirusInfectionException

"Scans only" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

fileName - The name of the file to be scanned.

jobID - A freely selectable job identifier.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanFile

public boolean scanFile(java.lang.String fileName)
                 throws VSIServiceException,
                        VirusScanException,
                        VirusInfectionException

"Scans only" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

fileName - The name of the file to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytes

public boolean scanBytes(java.lang.String objectName,
                         byte[] byteArray,
                         long len,
                         long jobID)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

"Scan only" for viruses withing a passed byte array. Scan takes place in the memory. Can be used if you have already read the object into a buffer.

Parameters:

objectName - Printable name of the object to be scanned.

byteArray - A byte array to be scanned.

len - The maximum length of the array to be scanned.

jobID - A free selectable job identifier.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytes

public boolean scanBytes(java.lang.String objectName,
                         byte[] byteArray,
                         long len)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

Scan the length of an array of bytes.

Parameters:

objectName - Printable name of the object to be scanned.

byteArray - Byte array.

len - Length of array to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytes

public boolean scanBytes(byte[] byteArray,
                         long len)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

Scan the length of an array of bytes.

Parameters:

byteArray - Byte array.

len - Length of array to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytes

public boolean scanBytes(byte[] byteArray)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

Scan an array of bytes.

Parameters:

byteArray - Byte array.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanFileEx

public boolean scanFileEx(boolean doClean,
                          java.lang.String fileName,
                          long jobID)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Extended Version of scanFile. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

fileName - The name of the file to be scanned.

jobID - A free selectable job identifier.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanFileEx

public boolean scanFileEx(boolean doClean,
                          java.lang.String fileName)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Extended Version of scanFile. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

fileName - The name of the file to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytesEx

public boolean scanBytesEx(boolean doClean,
                           java.lang.String objectName,
                           byte[] byteArray,
                           long len,
                           long jobID)
                    throws VSIServiceException,
                           VirusScanException,
                           VirusInfectionException

Extended Version of scanBytes. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

objectName - Printable name of the object to be scanned.

byteArray - A byte array to be scanned.

len - The maximum length of the array to be scanned.

jobID - A free selectable job identifier.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytesEx

public boolean scanBytesEx(boolean doClean,
                           java.lang.String objectName,
                           byte[] byteArray,
                           long len)
                    throws VSIServiceException,
                           VirusScanException,
                           VirusInfectionException

Extended Version of scanBytes. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

objectName - Printable name of the object to be scanned.

byteArray - A byte array to be scanned.

len - The maximum length of the array to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytesEx

public boolean scanBytesEx(boolean doClean,
                           byte[] byteArray,
                           long len)
                    throws VSIServiceException,
                           VirusScanException,
                           VirusInfectionException

Extended Version of scanBytes. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

byteArray - A byte array to be scanned.

len - The maximum length of the array to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

scanBytesEx

public boolean scanBytesEx(boolean doClean,
                           byte[] byteArray)
                    throws VSIServiceException,
                           VirusScanException,
                           VirusInfectionException

Extended Version of scanBytes. "Scan and Clean" for viruses. Means initiate the VSA to scan. The necessary parameters should be set with VsiSetParameter.

Parameters:

doClean - True means with clean action, false is equal to scan only.

byteArray - A byte array to be scanned.

Returns:

true - The scan was completely successful - no virus, no scan error.
false - The scan was not successful. The detailed problem description has to be retrieved by the corresponding exception.

Throws:

VSIServiceException - Problems reported with this exception can be communicated to external systems because they reflect error in the data sent by the caller.

VirusScanException - Problems reported with this exception occure during a virus scan (or clean) action. More detailed information can be retrieved by getScanErrors.

VirusInfectionException - Problems reported with this exception occure during a virus scan (or clean) action on a found infection. More detailed information can be retrieved by getInfections.

cleanFile

public boolean cleanFile(java.lang.String fileName,
                         long jobID)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

Scans and "tries to" clean infected files.

Parameters:

fileName - The name of the file to be scanned.

jobID - A freely selectable job identifier.

Returns:

true (on success)

cleanFile

public boolean cleanFile(java.lang.String fileName)
                  throws VSIServiceException,
                         VirusScanException,
                         VirusInfectionException

Scans and "tries to" clean infected files.

Parameters:

fileName - The name of the file to be scanned.

Returns:

true (on success)

cleanBytes

public boolean cleanBytes(java.lang.String objectName,
                          byte[] byteArray,
                          long len,
                          long jobID)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Scan and "tries to" clean the infected byte array.

Note:

If the byte array was "infection and repaired", the array is then smaller than before. If you want know the new length, call getCleanedLength()

Parameters:

objectName - The name of the scan object.

byteArray - A byte array to be scanned.

len - The maximum length of the array to be scanned.

jobID - A freely selectable job identifier.

Returns:

true (on success)

See Also:

getCleanedLength()

cleanBytes

public boolean cleanBytes(java.lang.String objectName,
                          byte[] byteArray,
                          long len)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Scan and clean the length of an array of bytes.

Parameters:

objectName - Printable name of the object to be scanned.

byteArray - Byte array.

len - Length of array to be scanned.

Returns:

true (on success)

cleanBytes

public boolean cleanBytes(byte[] byteArray,
                          long len)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Scan and clean the length of an array of bytes.

Parameters:

byteArray - Byte array.

len - Length of array to be scanned.

Returns:

true (on success)

cleanBytes

public boolean cleanBytes(byte[] byteArray)
                   throws VSIServiceException,
                          VirusScanException,
                          VirusInfectionException

Scan and clean an array of bytes.

Parameters:

byteArray - Byte array.

Returns:

true (on success)

getCleanedLength

public long getCleanedLength()
                      throws VSIServiceException,
                             VirusScanException

Returns:

Length of the cleaned byte array.

getJobID

public long getJobID()
              throws VSIServiceException

Returns:

JobID

setJobID

public void setJobID(long jobID)

Set the JOB identifier.

Returns:

none

getInfections

public Infection[] getInfections()
                          throws VSIServiceException,
                                 VirusScanException

Deprecated. Do not use

Get the last occured infections.

Returns:

Infection[] object.

getScanErrors

public ScanError[] getScanErrors()
                          throws VSIServiceException,
                                 VirusScanException

Deprecated. Do not use

Get the last occured scan errors.

Returns:

ScanError[] object.

getLastErrorRC

public int getLastErrorRC()

Return the last occured error code.

Returns:

Return code from VSIConstans

See Also:

VSIConstants

setScanInfo

public void setScanInfo(boolean bScanInfo)

Parameters:

bScanInfo - Boolean flag to determine whether this detailed information should be returned. default is true

setActiveContent

public void setActiveContent(boolean bActiveContent)

Deprecated. this method has no effect

Flag for notification

setParameter

public boolean setParameter(Parameter vsParameter)
                     throws VSIServiceException

Set a parameter

Parameters:

vsParameter - VSA parameter

Returns:

true (on success)

getParameters

public Parameter[] getParameters()
                          throws VSIServiceException

Get all VSA parameters

Returns:

Parameter[] object

getParameter

public Parameter getParameter(java.lang.String paramName)
                       throws VSIServiceException

Get parameter from VSA

Parameters:

paramName - Name of the param.

Returns:

Parameter object

setDefaultConfig

public boolean setDefaultConfig()
                         throws VSIServiceException

Set or reset the default configuration of a VSA.

Returns:

true (on success)