NAME

Net::IMP::Base - base class for Net::IMP analyzers

SYNOPSIS

    package mySessionLog;
    use base 'Net::IMP::Base';
    use fields qw(... local fields ...);

    sub new_analyzer {
        my ($class,%args) = @_;
        ... handle local %args ...
        my $self = $class->SUPER::new_analyzer(%args);
        ...
        return $self
    }

    sub data {
        my ($self,$dir,$data,$offset) = @_;
        ... analyse data ...
        ... propagate results with $self->run_callback ...
    }

DESCRIPTION

Net::IMP::Base is a class to make it easier to write IMP analyzers. It can not be used on its own but should be used as a base class in new analyzers.

It provides the following interface:

$class->new_analyzer(%args)

Called from <$factory-new_analyzer(%fargs)>> for creating the analyzer for a new pair of data streams. The arguments will be a combination of the %fargs given when creating the factory with new_factory and %args given when using the factory with new_analyzer.

Derived classes should handle (and remove) all local settings from %args and then call <$class-SUPER::new_analyzer(%rest_args)>> to construct $self.

This method might generate results already. This might be the case, if it needs to analyze only one direction (e.g. issue IMP_PASS with IMP_MAXOFFSET for the other direction) or if it needs to only intercept data but not deny or modify based on the data (e.g. issue IMP_PREPASS with IMP_MAXOFFSET).

Net::IMP::Base supports only two elements in %args, any other elements will cause an error:

meta

This will be stored in $self-{meta}>. Usually used for storing context specific information from the application. Some modules (like Net::IMP::SessionLog) depend on meta providing a hash reference with specific entries.

cb

This is the callback and will be stored in $self-{cb}>. Callback should be specified as an array reference with [$sub,@args]. See set_callback method for more information.

If you set the callback this way, you have to be prepared to handle calls to the callback immediatly, even if new_analyzer did not return yet. If you don't want this, use set_callback after creating the analyzer instead.

rv

A list of initial results can be given. This is usually not a good idea.

$self->data($dir,$data,$offset)

Will be called from the user of the analyzer whenever new data (or eof) are available. $dir is the direction (0|1), $data are the data ('' to mark eof) and $offset is the position in the input stream where $data start.

$offset must only be given from the caller if there were gaps in the input stream (which are allowed for IMP_PASS results with an offset in the future).

This method will contain the analyzer specific processing. Results from the analyzer will be propagated to the caller using run_callback.

$self->run_callback(@results)

This method should be called from the analyzer object from within the data method to propagate results using the callback provided by the user of the analyzer. It will propagate all spooled results and new results given to this method.

Each result is an array reference, see Net::IMP for details.

$self->add_results(@results)

This method adds new results to the list of collected results, but will not call any callbacks. It will usually be used in the analyzer from within the data method.

$self->set_callback($sub,@args)

This will set the callback ($self-{cb}>). This method will be called from the user of the analyzer. The callback will be used within run_callback and called with $sub->(@args,@results).

If there are already collected results, the callback will be executed immediately. If you don't want this, remove these results upfront with poll_results.

$self->poll_results

This will return the current @results and remove them from collected results. It will only be used from the caller of the analyzer if no callback is set.

Also a method is defined to check configuration:

$class->validate_cfg(%config)

This will return a list of errors with the config, e.g. it will return an empty list if no errors where detected.

Additionally the following methods are defined to aid in using configuration from a single string:

$class->cfg2str(%config) -> $string

Creates a string from a (configuration) hash. The output is similar to encoded query parameters in URLs.

$class->str2cfg($string) -> %config

Parses a configuration string generated by cfg2str and restores the configuration hash.

AUTHOR

Steffen Ullrich <sullr@cpan.org>

COPYRIGHT

Copyright by Steffen Ullrich.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.