##! Internal functions and types used by the logging framework.

module FileAnalysis;

%%{
#include "file_analysis/Manager.h"
%%}

type Info: record;
type ActionArgs: record;
type ActionResults: record;

## An enumeration of possibly-interesting "events" that can occur over
## the course of analyzing files.  The :bro:see:`FileAnalysis::policy`
## hook is called each time a trigger occurs.
enum Trigger %{
	## Raised when any part of a new file is detected.
	TRIGGER_NEW,
	## Raised when file analysis has likely seen a complete file.  That
	## is when a number of bytes indicated by the *total_bytes* field of
	## :bro:see:`FileAnalysis::Info` have been processed.  Note that
	## the *undelivered* field does not have to be zero for this to have
	## occurred.
	TRIGGER_DONE,
	## Raised when file analysis for a given file is aborted due
	## to not seeing any data for it recently.  Note that this doesn't
	## necessarily mean the full file wasn't seen (e.g. if the
	## :bro:see:`FileAnalysis::Info` record indicates the file *total_bytes*
	## isn't known).  Use :bro:see:`FileAnalysis::postpone_timeout`
	## during a :bro:see:`FileAnalysis::policy` handler for this trigger to
	## defer the timeout until later.
	TRIGGER_TIMEOUT,
	## Raised when the beginning of a file is detected.
	TRIGGER_BOF,
	## Raised when the beginning of a file is available and that beginning
	## is at least the number of bytes indicated by the *bof_buffer_size*
	## field of :bro:see:`FileAnalysis::Info`.
	TRIGGER_BOF_BUFFER,
	## Raised when an initial guess at the file/mime type of a file is matched
	## based on magic numbers.
	TRIGGER_TYPE,
	## Raised to signal that no more file data is incoming and it couldn't be
	## determined whether the full file was actually seen.
	TRIGGER_EOF,
	## The reassembly buffer for the file filled and had to be discarded.
	## The *undelivered* field of :bro:see:`FileAnalysis::Info` will
	## indicate the number of bytes, if any, that were not all-in-sequence.
	## TODO: Is it possible to extend the reassembly buffer when "handling"
	## this trigger?
	TRIGGER_REASSEMBLY_BUFFER_FULL,
	## Raised when there's a missing chunk of data in the file stream.
	TRIGGER_GAP,
%}

enum Action %{
	ACTION_EXTRACT,
	ACTION_MD5,
	ACTION_SHA1,
	ACTION_SHA256,
	ACTION_DATA_EVENT,
%}

function FileAnalysis::postpone_timeout%(file_id: string%): bool
	%{
	using file_analysis::FileID;
	bool result = file_mgr->PostponeTimeout(FileID(file_id->CheckString()));
	return new Val(result, TYPE_BOOL);
	%}

function FileAnalysis::add_action%(file_id: string, args: any%): bool
	%{
	using file_analysis::FileID;
	using BifType::Record::FileAnalysis::ActionArgs;
	RecordVal* rv = args->AsRecordVal()->CoerceTo(ActionArgs);
	bool result = file_mgr->AddAction(FileID(file_id->CheckString()), rv);
	Unref(rv);
	return new Val(result, TYPE_BOOL);
	%}

function FileAnalysis::remove_action%(file_id: string, args: any%): bool
	%{
	using file_analysis::FileID;
	using BifType::Record::FileAnalysis::ActionArgs;
	RecordVal* rv = args->AsRecordVal()->CoerceTo(ActionArgs);
	bool result = file_mgr->RemoveAction(FileID(file_id->CheckString()), rv);
	Unref(rv);
	return new Val(result, TYPE_BOOL);
	%}

function FileAnalysis::stop%(file_id: string%): bool
	%{
	using file_analysis::FileID;
	bool result = file_mgr->IgnoreFile(FileID(file_id->CheckString()));
	return new Val(result, TYPE_BOOL);
	%}

function FileAnalysis::input_data%(source: string, data: string%): any
	%{
	file_mgr->DataIn(data->Bytes(), data->Len(), source->CheckString());
	return 0;
	%}

function FileAnalysis::input_data_chunk%(source: string, data: string,
                                         offset: count%): any
	%{
	file_mgr->DataIn(data->Bytes(), data->Len(), offset, source->CheckString());
	return 0;
	%}

function FileAnalysis::gap%(source: string, offset: count, len: count%): any
	%{
	file_mgr->Gap(offset, len, source->CheckString());
	return 0;
	%}

function FileAnalysis::set_size%(source: string, size: count%): any
	%{
	file_mgr->SetSize(size, source->CheckString());
	return 0;
	%}

function FileAnalysis::input_eof%(source: string%): any
	%{
	file_mgr->EndOfFile(source->CheckString());
	return 0;
	%}