NAME

Net::IMP::Base - base class to make writing of Net::IMP analyzers easier

SYNOPSIS

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

    # plugin methods
    # sub new_factory ...  - has default implementation
    # sub cfg2str ...      - has default implementation
    # sub str2cfg ...      - has default implementation
    sub validate_cfg ...   - needs to be implemented

    # factory methods
    sub INTERFACE ...      - needs to be implemented
    # sub interface ...    - has default implementation using sub INTERFACE
    sub new_analyzer ...   - needs to be implemented

    # analyzer methods
    sub data ...           - needs to be implemented
    # sub poll_results ... - has default implementation
    # sub set_callback ... - has default implementation

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 for the global plugin API as required for all Net::IMP plugins.

cfg2str|str2cfg

These functions convert a %config to or from a $string. In this implementation the <$string> is a single line, encoded similar to the query_string in HTTP URLs.

There is no need to re-implement this function unless you want to serialize the config into a different format.

$class->validate_cfg(%config)

This function verifies the config and thus should be reimplemented in each sub-package.

The implementation in this package just complains, if there are any data left in %config and thus should be called with any config data not handled by your own validation function.

$class->new_factory(%args)

This will create a new factory class. %args will be saved into $factory-{factory_args}> and later used when creating the analyzer. There is no need to re-implement this method.

The following methods are implemented on factory objects as required by Net::IMP:

$factory->interface(@in) => @out

This method provides an implementation of the interface API function. This implementation requires the implementation of a function INTERFACE like this:

  sub INTERFACE { return (
    [ 
      # require HTTP data types
      IMP_DATA_HTTP,          # input data types/protocols
      [ IMP_PASS, IMP_LOG ]   # output return types
    ],[
      # we can handle stream data too if we use a suitable adaptor
      IMP_DATA_STREAM, 
      [ IMP_PASS, IMP_LOG ],
      'Net::IMP::Adaptor::STREAM2HTTP',
    ]
  )}

There is no need to re-implement method interface, but INTERFACE should be implemented. If your plugin can handle any data types you can set the type to undef in the interface description.

$factory->new_analyzer(%args)

This method is called from <$factory-new_analyzer(%fargs)>> for creating the analyzer for a new pair of data streams.

This implementation will create a new analyzer object based on the factory object, e.g. it will use %args for the fields in the analyzer but also provide access to the args given when creating the factory within field factory_args.

If the interface required an adaptor it will wrap the newly created analyzer into the adaptor with $analyzer = $adaptor_class->new($analyzer).

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

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 $analyzer-{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 $analyzer-{analyzer_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.

The following methods are implemented on analyzer objects as required by Net::IMP:

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

This will set the callback ($analyzer-{analyzer_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.

$analyzer->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.

$analyzer->data($dir,$data,$offset,$dtype)

This method should be defined for all analyzers. The implementation in this package will just croak.

Also the following methods are defined for analyzers and can be used inside your own analyzer.

$analyzer->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.

$analyzer->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.

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.