NAME¶
Courier::Filter::Module - Abstract Perl base class for filter modules used by
the Courier::Filter framework
SYNOPSIS¶
Courier::Filter message filtering¶
use Courier::Filter::Module::My; # Need to use a non-abstract sub-class.
my $module = Courier::Filter::Module::My->new(
logger => $logger,
inverse => 0,
trusting => 0,
testing => 0,
debugging => 0
);
my $filter = Courier::Filter->new(
...
modules => [ $module ],
...
);
Deriving new filter module classes¶
package Courier::Filter::Module::My;
use base qw(Courier::Filter::Module);
DESCRIPTION¶
Sub-classes of
Courier::Filter::Module are used by the
Courier::Filter mail filtering framework to determine the acceptability
of messages. See Courier::Filter::Overview for an overview of how filter
modules are used and for how to write them.
When overriding a method in a derived class, do not forget calling the inherited
method from your overridden method.
Constructor¶
The following constructor is provided and may be overridden:
- new(%options): returns Courier::Filter::Module
- Creates a new filter module using the %options. Initializes the filter
module, by opening I/O handles, connecting to databases, creating
temporary files, initializing parser libraries, etc..
%options is a list of key/value pairs representing any of the following
options:
- logger
- A Courier::Filter::Logger object that will be used for logging
message rejections and error messages caused by this individual filter
module. If no logger is specified, Courier::Filter's global logger will be
used.
- inverse
- A boolean value controlling whether the filter module should operate with
inverse polarity ( true) as opposed to normal polarity
(false). Under inverse polarity, the result of the
"match" method is negated by the "consider" method
before returning it. For details on how Courier::Filter translates
match results into acceptability results, see "How
filter modules work" in Courier::Filter::Overview. Defaults to
false.
- trusting
- A boolean value controlling whether the filter module should not be
applied to trusted messages. For details on how the trusted status is
determined, see the description of the "trusted" property in
Courier::Message. In most configurations, this option can be used to
white-list so-called outbound messages. Defaults to
false.
- testing
- A boolean value controlling whether the filter module should run in
testing mode. In testing mode, planned message rejections will be logged
as usual, but no messages will actually be rejected. Defaults to
false.
- debugging
- A boolean value controlling whether the filter module should log extra
debugging information. Defaults to false.
Derived classes may support additional options.
"Courier::Filter::Module::new()" creates a hashref as an object of the
invoked class, and stores the %options in it, but does nothing else.
Destructor¶
The following destructor is provided and may be overridden:
- destroy
- Uninitializes the filter module, by closing I/O handles, disconnecting
from databases, deleting temporary files, uninitializing parser libraries,
etc..
"Courier::Filter::Module::destroy()" does nothing. Sub-classes may
override this method and define clean-up behavior.
Class methods¶
The following class methods are provided and may be overridden:
- warn($text)
- Writes a warning message to syslog. This method may also be used as an
instance method.
Instance methods¶
The following instance methods are provided and may be overridden:
- consider($message): returns string, [string]; throws
Perl exceptions
- Calls the "match" method, passing it the $message object.
Returns the result of "match", negating it beforehand if the
filter module has inverse polarity. There is usually no need at all to
override this method.
- match($message): returns string, [string]; throws
Perl exceptions
- Examines the Courier::Message object given as $message. Returns a
so-called match result consisting of an SMTP status response
text, and an optional numerical SMTP status response code.
For details about how match results are used by Courier::Filter,
see "How filter modules work" in Courier::Filter::Overview and
"Writing filter modules" in Courier::Filter::Overview.
"Courier::Filter::Module::match()" does nothing and returns
undef. Sub-classes should override this method and define their own
matching rule.
- logger: returns Courier::Filter::Logger
- logger($logger): returns Courier::Filter::Logger
- If $logger is specified, installs a new logger for this individual filter
module. Returns the current (new) logger.
- inverse: returns boolean
- Returns a boolean value indicating whether the filter module is operating
with inverse polarity, as set through the constructor's
"inverse" option.
- trusting: returns boolean
- Returns a boolean value indicating whether the filter module does
not apply to trusted messages, as set through the constructor's
"trusting" option.
- testing: returns boolean
- Returns a boolean value indicating whether the filter module is in testing
mode, as set through the constructor's "testing" option.
- debugging: returns boolean
- debugging($debugging): returns boolean
- If $debugging is specified, sets the debugging mode for this individual
filter module. Returns the (newly) configured debugging mode.
SEE ALSO¶
Courier::Filter, Courier::Filter::Module.
For a list of prepared loggers that come with Courier::Filter, see "Bundled
Courier::Filter loggers" in Courier::Filter::Overview.
For AVAILABILITY, SUPPORT, and LICENSE information, see
Courier::Filter::Overview.
AUTHOR¶
Julian Mehnle <julian@mehnle.net>