NAME

Mail::IspMailGate::Filter - An abstract base class of mail filters

SYNOPSIS

 # Create a filter
 my($filter) = Mail::IspMailGate::Filter->new({});

 # Call him for filtering a given mail (aka MIME::Entity)
 my ($attr) = {
     'entity' => $entity,    # a MIME::Entity object
     'parser' => $parser     # a MIME::Parser object
 };
 my($res) = $filter->doFilter($attr); 

VERSION AND VOLATILITY

    $Revision 1.0 $
    $Date 1998/04/05 18:19:45 $

DESCRIPTION

This class is the abstract base class of email filters. It implements the main functionality every email filter should have, such as recursive filtering on multipart MIME-message. You create a new filter by deriving a subclass from Mail::IspMailGate::Filter. Usually you only need to implement your own versions of the getSign, filterFile and IsEq methods.

Most filters are in/out filters. For example the packer module can do compression or decompression and the PGP module can do encryption and decryption. These filters are derived from Mail::IspMailGate::Filter::InOut, which is itself derived from Mail::IspMailGate::Filter. The main idea of these filters is that they have two directions, a 'positive' direction (or 'in' mode) and a negative direction (or 'out' mode).

PUBLIC INTERFACE

new $ATTR

Class method. Create a new filter instance; by passing the hash ref ATTR you configure the filters behaviour. For example, the PGP filter typically needs a user ID, the virus scanner needs a path to the external virus scanning binary and so on.

The method returns an object for success or an error message otherwise.

getSign

Instance method. Returns a header name, that will be inserted into the MIME entities head. For example, the base class inserts a header field "X-ispMailGateFilter". Note that more than one header line will be inserted if you apply multiple filters.

You should override this method.

filterFile $ATTR

Instance method. This method is called for modifying a given, single part of the MIME entity. You can rely on the following attributes being set in the hash ref ATTR:

body

The MIME::Body object representing the part. The true data is stored as a file on disk. (It's a MIME::Body::File object, to be precise.) In particular this means that you can create a handle referring to the object with

 $fh = $ATTR->{'body'}->open("r") or die $!;

If you need to work with external binaries you might use

 $path = $ATTR->{'body'}->path();

If the external binaries create a new file and you want to replace the old file, use

 $ATTR->{'body'}->path($newPath);

See MIME::Body(3) for detailed information.

head

The MIME::Head object representing this parts head. See MIME::Head(3) for detailed information.

globHead

The MIME::Head object of the top level MIME entity. If you are working on a single part entity, this is just the same as the 'head' attribute.

parser

The Mail::IspMailGate::Parser object used for parsing the entity. This is mostly usefull for using the logging methods

  $ATTR->{'parser'}->Debug("A debugging message");
  $ATTR->{'parser'}->Error("An error message");
  $ATTR->{'parser'}->Fatal("A fatal error message");

Note that the latter will abort the currently running thread, use is discouraged. Instead you should throw a Perl exception by calling die.

The filterFile method returns an empty string for success or an error message otherwise. You should override this function, but calling

 $self->SUPER::filterFile($ATTR)

at the beginning is strongly encouraged.

mustFilter $ENTITY

Instance method. This method determines, whether the doFilter method ought to be executed. Usually it looks at the headers of the MIME entity $ENTITY, for example the InOut class supresses filtering twice. The method returns FALSE to supress filtering, TRUE otherwise.

hookFilter $ENTITY

Instance method. If filtering was needed (see doFilter) and done, this method is called, mainly for modifying the headers of the MIME entity $ENTITY. When overriding this method, you should usually start with calling

 $self->SUPER::hookFilter($ENTITY);

doFilter $ATTR

Instance method. This method builds the frame of the filtering process. It calls mustFilter. If this method returns TRUE, the recdoFilter and hookFilter methods are executed.

The hash ref $ATTR contains attributes 'entity', 'parser' correspond to the same attributes of the filterFile method.

recdoFilter $ATTR

Instance method. Called by doFilter for filtering a MIME entity. It calls the filterFile method for singlepart entities. For multipart entities, it calls itself recursively for any part.

The hash ref $ATTR corresponds to the arguments of doFilter.

IsEq $CMP

Instance method. The IspMailGate program can handle multiple recipients at the same time, which is obviously important for performance reasons. For any recipient, a list of filters is built that the mail is fed into. In most cases these filter lists or at least parts of them are equivalent, so there's no need to pass the mail into both filter lists.

This method is called for determining whether two filter objects ($self and $CMP) are equivalent. In other words: If I feed a mail into both objects, the method tells me whether I can expect the same result. For example, a simple implementation of IsEq would just look at the filter object classes and return TRUE, if both objects are of the same classes, but FALSE otherwise:

  sub IsEq ($$) {
      my($self, $CMP) = @_;
      ref($self) eq ref($CMP);
  }

The above is the default implementation, so it's quite likely that you need to override this method.