Scan a file (COM)

Method

ScanEx

Description

This method is an extensible scan API which allows the setting of various scan options that can be configured for each scan request.

Function prototype

HRESULT ScanEx
(
[in] VARIANT ContentsToScan,
[in] VARIANT* InArgsArray,
[out, retval] VARIANT* OutArgsArray
)

Arguments

Argument

Description

Data Type

ContentsToScan

This argument may hold one of four types: a file path to be scanned, a file signature to be scanned, a boot sector to be scanned, or a memory buffer to be scanned, based on the data type of this parameter and input argument (InArgsArray) value

  • File path: if the type of this parameter is a string and the fifth argument of InArgsArray is set to 0 or the size of InArgsArray is 3

  • File signature: if the type of this parameter is a string and the fifth argument of InArgsArray is set to 1

  • Boot sector scan: if the type of this parameter is a string and the fifth argument of InArgsArray is set to 2

  • Memory buffer: if the type of this parameter is a byte array(byte[])

  • Virtual Machine image folder path

File name: string

Buffer: byte array

InArgsArray

A list of input arguments in following order:

  1. (boolean) Sync flag (true: synchronous scan , false or invalid value: asynchronous scan)

  2. (boolean) Clean flag (true: Action on dirty file, false: keep)

  3. (UINT32) Custom ticket #

    - maximum 9 digits from 1-999999999 or 0 for not using custom ticket #

  4. (UINT32) Analyze before scan

    0: disable analyze file before scan

    1: enable analyze file before scan

    2: use global setting (“analyze_before_scan”)

  5. (UINT32) Contents Type

    0: ContentToScan argument holds file path or memory buffer

    1: ContentToScan argument holds SHA1-based signature.

    2: ContentToScan argument holds driver letter for a boot sector scan

    4: ContentToScan argument holds Virtual Machine image folder path (Virtual machine disk must contain a Windows based filesystem)

  6. (UINT32) Clean Action Type

    0: take no action

    1: quarantine (ignore global setting, “clean_action”)

    2: delete (ignore global setting, “clean action”)

    3: follow global setting

  7. (UINT32) Caching option

    0: disable to cache for this scan request

    1: enable to cache for this scan request

    2:rescan (disregard existing cache and update with new scan result)

    3: use global setting(“enable_cache_scan”)

  8. (String) Password for encrypted archive.

    - Use empty string to when no password is required.(“enable_cache_scan”)

  9. (String) User agent

    - This is used to associate scan history with the source of scan request. Empty string is allowed.

  10. (String) User description

    - This will be logged along with scan request for the caller’s purpose. Empty string is allowed.

    - Pass the following JSON formatted string to control the file name and file path to be logged:

    {"file_info.original_file_path":"<original file path not including file name", "file_info.display_name":"<original file name>"}

  11. (UINT32) Configure logging

    0: disable logging this particular scan request

    1: enable logging this particular scan request

    2: use global setting (omsConfig.ini)

  12. (UINT32) Archive File Handling

    0: do not extract archive file for this particular request

    1: extract archive file for this particular scan request

    2: use global setting (“internal_archive_lib_enable”)

Array of variants

OutArgsArray

A list of outputs with the following order:

  1. (UINT32) Ticket number (if custom ticket # is specific in InargsArray, same ticket number is returned

  2. (UINT32) Scan result as described in ScanOutCome Return Type

  3. (Array of strings) List of threats
    (String) Scan detail per engine

    <scan_details>
    <objects>
    <object name="[object name]">
    <engine_result>
    <engine_name>[engine name]</name>
    <scan_result>[scan outcome for the engine]</scan_result>
    </engine_result>
    </object>
    </objects>
    </scan_details>

    [object_name]: file name or signature depends on type of scan requested

    [scan outcome for the engine]: Scan result per engine as described in ScanOutCome Return Type

  4. (String) File type information

    this is returned only if analyze_before_scan is enabled orthe third argument of InArgsArray is set to 1

    <file_type>
    <objects size="">
    <object>
    <sha1></sha1>
    <type_infos size="">
    <type_info>
    <long></long>
    <short></short>
    <extension></extension>
    </type_info>
    </type_infos>
    </object>
    </objects>
    </file_type>