Callback for Processing a File (COM)

Method

OnProcess

Description

This callback is fired after each Process method when a pre-defined event is found.

Note

Connection Points

Function prototype

void OnProcess
(
[out] VARIANT *OutDetail,
[out, retval] VARIANT *OutArgsArray
)

Arguments

Argument

Description

Data Type

OutDetail

The details from this event. The JSON schema depends on the callback type. See ‘‘callback types’’ for more details.

string

OutArgsArray

0: CallBackType: Since OnProcess is a general callback that is fired for different events, this specifies the event type. See the callback types for details of the type.

1: Ticket: The ticket returned from the Process API. For example 974989300.

2: The final result of processing the specified file through a workflow

1 = The file was allowed. JSON equivalent is "Allowed"

2 = The file was blocked. JSON equivalent is "Blocked"

3 = The file is currently being processed. JSON equivalent is "Processing"

Safearray of variants with the following order

0: UINT32

1: string

2: UINT32

Callback types

Callback Type

Description

Example JSON

2

This callback method is invoked whenever each engine completes the scan. This callback can be used for a progress report of scanning when more than one engine is used. If engines are not used for any reason such as encrypted archive or scan request on a known file, no progress report is fired.

Example
{
    "type": "ScanProgressReport",
    "ticket": 974989300,
    "scan_result": "1",
    "threat_list": [
        "eicar",
        "eicar"
    ],
    "product_name": "Clamwin Scan Engine",
    "scan_start_time": "6/5/2014 2:32 PM",
    "scan_end_time": "6/5/2014 2:32 PM",
    "scan_time_(ms)": "1",
    "file_path": "C:\\some\\file.txt",
    "process_result": "Processing"
}

4

This connection point is fired whenever a scan is completed. This event is not global but specific to the client that makes this scan request. In other words, when scanning is requested by a client, other client objects will not get a callback when the scanning is completed.

Example
{
    "type": "OnScanComplete",
    "ticket": 974989300,
    "scan_result": "1",
    "threat_list": [
        "eicar",
        "eicar"
    ],
    "scan_start_time": "6/5/2014 2:32 PM",
    "scan_end_time": "6/5/2014 2:32 PM",
    "scan_time_(ms)": "2",
    "file_path": "C:\\some\\file.txt",
    "process_result": "Processing"
}

7

This callback method is invoked when Process' archive handling is enabled and an archive was successfully extracted.

This callback can be used to determine if a processed file is an archive.

Example
{
    "type": "ArchiveFileInfo",
    "ticket": 783676241,
    "file_path": "2files_dirty.zip",
    "process_result": "Processing"
}

8

This is fired after a file has been fully processed through each stage of a workflow.

FTC Details

If FTC is enabled and copy/move is disabled, the converted file appears next to the original file.

If FTC and copy/move are enabled, the converted file location will be reported in "post_processing.copy/move_destination"

Collisions are handled by incrementing the file name: file_name.txt , file_name_1.txt , file_name_2.txt , ..

Possible Blocked Reasons

  • Failed to start the processing job: "Process Failed"

  • Mismatch detected: "Mismatch"

  • File type disallowed: "Filtered"

  • Scan Result: "Known | ("Dirty" or "Infected") | Suspicious | Failed | Cleaned | Unknown | ("Skipped Dirty" or "Skipped Infected") | Not Scanned | Aborted | Password Protected Document"

  • Archive: "Encrypted Archive | Missing File During Extraction | Insufficient Space For Archive Extraction | Exceeded Archive Size | Exceeded Archive File Number | Archive Extraction Error | Exceeded Archive Depth | Archive Error"

  • Post Action: "Sanitization Failed" (Copy or Quarantine failure will not cause blocked result)

Possible Process Results

  • "Allowed": the file is allowed

  • "Blocked": the file is blocked

  • "Processing": the file is currently being processed

Possible Action Ran Results

  • Sanitized

  • Copied

  • Moved

  • Quarantined

  • Deleted

  • Ran Script

*Copied and Moved will never exist together
*Quarantined and Deleted will never exist together
*(Copied/Moved) and (Quarantined/Deleted) will never exist together

Example
{
    "type": "ProcessComplete",
    "ticket": "974989300",
    "process_result": "Allowed",
    "file_path": "C:\\some\\file.txt",
    "user_agent": "metascan_rest",
    "profile": "Default",
    "file_type_skipped_scan": false,
    "blocked_reason": ""
}

If Post Processing is ran:

Example
{
    "type": "ProcessComplete",
    "ticket": "974989300",
    "process_result": "Allowed",
    "file_path": "C:\\some\\toConvert.docx",
    "user_agent": "metascan_rest",
    "profile": "Default",
    "file_type_skipped_scan": false,
    "blocked_reason": "",
    "post_processing": {
        "actions_ran": "Converted | Quarantined | Moved",
        "actions_failed": "Convert Failed | Quarantine Failed",
    	"converted_to": "pdf",
    	"copy_destination": "C:\\toConvert.pdf"
    }
}

9

This callback is fired for AnalyzeFileType. It will be fired for a single file as well as for individual files within an archive.

For a single file it will be a fully qualified path, such as: "C:\\level1\\file.txt"

For a file inside an archive it will be prefixed with \\, such as: "\\level1\\file.txt"

Example
{
    "type": "FileTypeAnalyze",
    "ticket": "974989300",
    "file_path": "C:\\some\\toConvert.docx",
    "file_size": 5134
    "file_type_category" : "E",
    "file_type_description" : "Win64 Executable (generic)",
    "file_type_extension" : "EXE/DLL",
    "md5": "20A2DFB5EC69BCEA66203CF0907791FD",
    "sha1": "6D5052FC0ED06C0D975F19D79AFEB5454F3926D3",
    "sha256": "4A7C7077F929041D2D2A1899A8D28751B097A4DA41EFAAE022C0DE9F18282FE4",
    "process_result": "Processing"
}