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);

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:

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.