Index
Code Index:
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
doFiltermethod 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, therecdoFilterandhookFiltermethods are executed.The hash ref $ATTR contains attributes 'entity', 'parser' correspond to the same attributes of the
filterFilemethod. - recdoFilter $ATTR
-
Instance method. Called by
doFilterfor filtering a MIME entity. It calls thefilterFilemethod 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.