Courier::Filter::Module - An abstract Perl base class for filter modules used by the Courier::Filter framework

0.16

    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 ],
        ...
    );

    package Courier::Filter::Module::My;
    use base qw(Courier::Filter::Module);

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.

The following constructor is provided and may be overridden:

new(%options): RETURNS Courier::Filter::Module (or derivative)

Creates a new filter module using the CW%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 CWmatch method is negated by the CWconsider method before returning it. For details on how Courier::Filter translates match results into acceptability results, see How Courier::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 authenticated status is determined, see the description of the CWtrusted 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. CWCourier::Filter::Module::new() creates a hashref as an object of the invoked class, and stores the CW%options in it, but does nothing else.

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.. CWCourier::Filter::Module::destroy() does nothing.

The following instance methods are provided and may be overridden:

consider($message): RETURNS SCALAR, [SCALAR]; THROWS Perl exceptions

Calls the CWmatch method, passing it the CW$message object. Returns the result of CWmatch, negating it beforehand if the filter module has inverse polarity. There is usually no need at all to override this method.

match($message): RETURNS SCALAR, [SCALAR]; THROWS Perl exceptions

Examines the Courier::Message object given as CW$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 Courier::Filter modules work in Courier::Filter::Overview and Writing Courier::Filter modules in Courier::Filter::Overview. CWCourier::Filter::Module::match() does nothing and returns undef.

logger: RETURNS Courier::Filter::Logger

logger($logger): RETURNS Courier::Filter::Logger

If CW$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 CWinverse 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 CWtrusting option.

testing: RETURNS boolean

Returns a boolean value indicating whether the filter module is in testing mode, as set through the constructor's CWtesting option.

debugging: RETURNS boolean

debugging($debugging): RETURNS boolean

If CW$debugging is specified, sets the debugging mode for this individual filter module. Returns the current (new) debugging mode.

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.

Julian Mehnle <julian@mehnle.net>