Virus Scan Engine API

Applies to: SharePoint Foundation 2010

This topic describes the API that is required for building a compliant Virus Scan Engine (VSE) for scanning and cleaning documents in Windows SharePoint Services 3.0. For a general introduction to the VSE and its requirements, see Overview: Virus Scan Engine API Implementation.

IMso_VirusScanner Interface

The following table describes the methods that are provided by the IMso_VirusScanner interface.

Method	Description
Initialize	Performs all per-instance initialization of the scanner and returns information about the current IMso_VirusScanner instance.
Scan	Scans content of the stream and returns infection status and virus information if available.
Clean	Attempts to remove virus infection from content.

Remarks

The host application instantiates an IMso_VirusScanner object and performs the following tasks:

• Instantiates the virus scanner as an INPROC_SERVER in a free-threaded apartment.

• Calls the Initialize method prior to calling any other method.

• Ensures that there are no outstanding Scan requests prior to calling Release.

• Makes simultaneous calls to Scan or Clean from multiple threads after the Initialize method has completed and before calling Release.

The compliant scanner is an instance of the IMso_VirusScanner interface and performs the following tasks:

• All initialization and resource allocation through the Initialize method.

• NO calls to any operating system APIs with uncertain completion time during scanning or cleaning. Examples include, but are not limited to, file I/O and registry manipulation.

Initialize Method

Performs all per-instance initialization of the scanner and returns information about the current IMso_VirusScanner instance.

Syntax

STDMETHOD Initialize (
      BSTR *pbstrProduct,
      DWORD *pdwProductVersion
);

Parameters

Parameter	Description
pbstrProduct [OUT]	Specifies the address of the variable that receives a string identifying the application of the vendor, as in "Microsoft Office Word 2007 (12.2627.2625)".
pdwProductVersion [OUT]	Specifies the address of the variable that receives the version of the signature file that the scanner is currently using.

Return Value

Success: Returns S_OK if initialization succeeds.

Failure: Returns an error code.

Remarks

This method must be called once per IMso_VirusScanner instance, immediately after the instance is created, and before any calls to the Scan or Clean method.

Scan Method

Scans content and returns infection status and virus information if available.

Syntax

STDMETHOD Scan (
      ILockBytes *pilb,
      DWORD *pdwStatus,
      BSTR *pbstrVirusInfo
);

Parameters

Parameter	Description
pilb [IN]	An object holding the content that is to be scanned. This object contains information regarding the file name and file type.
pdwStatus [OUT]	Specifies the address of the variable that receives the infection status of the content.
pbstrVirusInfo [OUT]	Specifies the address of the variable that receives a string with information relevant to a virus, if the content is infected. If the scanner detects several viruses, it needs to concatenate the strings and delimit them with the TAB (ASCII 9) character.

The host frees the returned value by using the SysFreeString function.

Return Value

Success: Returns S_OK if the operation completed successfully and the pdwStatus and pbstrVirusInfo parameters contain valid information.

Failure: Returns an error code.

Remarks

The host calls this method from several threads simultaneously. The scanner is expected to perform requests simultaneously without internal serialization of the requests.

Clean Method

Attempts to remove the virus infection from the content.

Syntax

STDMETHOD Clean (
      ILockBytes *pilbInput,
      ILockBytes *pilbOutput,
      DWORD *pdwStatus,
      BSTR *pbstrVirusInfo
);

Parameters

Parameter	Description
pilbInput [IN]	An object holding the content to be repaired. This object contains information regarding the file name and file type.
pilbOutput [IN]	An object receiving the repaired data. At the time of the method call, the contents of pilbInput and pilbOutput are identical, so the scanner needs to optimize I/O operations if possible.
pdwStatus [OUT]	Specifies the address of the variable that receives the infection status of the content.
pbstrVirusInfo [OUT]	Specifies the address of the variable that receives a string with information relevant to a virus, if the content is infected. If the scanner detects several viruses, it needs to concatenate the strings up to the length of the buffer, delimiting them with the TAB (ASCII 9) character.

The host frees the returned value by using the SysFreeString function.

Return Value

Success: Returns S_OK if the operation completed successfully and the pdwStatus, wzVirusInfo, and pilbOutput parameters contain valid information.

Remarks

The host calls this method from several threads simultaneously. The scanner is expected to perform requests simultaneously without internal serialization of requests.

ILockBytes Interface

The ILockBytes interface is exposed to allow the vendor to extract extra information about the file, which can include the file name, file type, file size, and so on. For a complete description of this interface on MSDN, see ILockBytes.

Syntax

typedef struct tagSTATSTG {
      LPWSTR pwcsName;
      DWORD type;
      ULARGE_INTEGER cbSize;
      FILETIME mtime;
      FILETIME ctime;
      FILETIME atime;
      DWORD grfMode;
      DWORD grfLocksSupported;
      CLSID clsid;
      DWORD grfStateBits;
      DWORD reserved;
} STATSTG;

Members

Member	Description
pwcsName	A pointer to a NULL-terminated Unicode string containing the name. The space for this string is allocated by the method called and freed by the caller, as with the COM CoTaskMemFree function. You can specify not to return this member by specifying the STATFLAG_NONAME value when you call a method that returns a STATSTG structure, except for calls to the IEnumSTATSTG::Next method, which provides no way to specify this value.
type	Indicates the type of storage object, which can be one of the values in the STGTY enumeration.
cbSize	Specifies the size in bytes of the stream or byte array.
mtime	Indicates the last modification time for this storage, stream, or byte array.
ctime	Indicates the creation time for this storage, stream, or byte array.
atime	Indicates the last access time for this storage, stream, or byte array.
grfMode	Indicates the access mode specified when the object was opened. This member is valid only in calls to Stat methods.
grfLocksSupported	Indicates the types of region locking that is supported by the stream or byte array, which can be a value in the LOCKTYPE enumeration. This member is not used for storage objects.
clsid	Indicates the class identifier for the storage object; set to CLSID_NULL for new storage objects. This member is not used for streams or byte arrays.
grfStateBits	Indicates the current state bits of the storage object; that is, the value most recently set by the IStorage::SetStateBits method. This member is not valid for streams or byte arrays.
reserved	Reserved for future use.