.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Courier::Filter::Module 3pm" .TH Courier::Filter::Module 3pm "2015-11-28" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Courier::Filter::Module \- Abstract Perl base class for filter modules used by the Courier::Filter framework .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Courier::Filter message filtering" .IX Subsection "Courier::Filter message filtering" .Vb 1 \& 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 ], \& ... \& ); .Ve .SS "Deriving new filter module classes" .IX Subsection "Deriving new filter module classes" .Vb 2 \& package Courier::Filter::Module::My; \& use base qw(Courier::Filter::Module); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Sub-classes of \fBCourier::Filter::Module\fR are used by the \fBCourier::Filter\fR 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. .PP When overriding a method in a derived class, do not forget calling the inherited method from your overridden method. .SS "Constructor" .IX Subsection "Constructor" The following constructor is provided and may be overridden: .IP "\fBnew(%options)\fR: returns \fICourier::Filter::Module\fR" 4 .IX Item "new(%options): returns Courier::Filter::Module" Creates a new filter module using the \f(CW%options\fR. Initializes the filter module, by opening I/O handles, connecting to databases, creating temporary files, initializing parser libraries, etc.. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP "\fBlogger\fR" 4 .IX Item "logger" A \fBCourier::Filter::Logger\fR 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. .IP "\fBinverse\fR" 4 .IX Item "inverse" A boolean value controlling whether the filter module should operate with inverse polarity (\fBtrue\fR) as opposed to normal polarity (\fBfalse\fR). Under inverse polarity, the result of the \f(CW\*(C`match\*(C'\fR method is negated by the \&\f(CW\*(C`consider\*(C'\fR method before returning it. For details on how Courier::Filter translates \fImatch results\fR into \fIacceptability results\fR, see \&\*(L"How filter modules work\*(R" in Courier::Filter::Overview. Defaults to \fBfalse\fR. .IP "\fBtrusting\fR" 4 .IX Item "trusting" A boolean value controlling whether the filter module should \fInot\fR be applied to trusted messages. For details on how the trusted status is determined, see the description of the \f(CW\*(C`trusted\*(C'\fR property in Courier::Message. In most configurations, this option can be used to white-list so-called \fIoutbound\fR messages. Defaults to \fBfalse\fR. .IP "\fBtesting\fR" 4 .IX Item "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 \fBfalse\fR. .IP "\fBdebugging\fR" 4 .IX Item "debugging" A boolean value controlling whether the filter module should log extra debugging information. Defaults to \fBfalse\fR. .RE .RS 4 .Sp Derived classes may support additional options. .Sp \&\f(CW\*(C`Courier::Filter::Module::new()\*(C'\fR creates a hashref as an object of the invoked class, and stores the \f(CW%options\fR in it, but does nothing else. .RE .SS "Destructor" .IX Subsection "Destructor" The following destructor is provided and may be overridden: .IP "\fBdestroy\fR" 4 .IX Item "destroy" Uninitializes the filter module, by closing I/O handles, disconnecting from databases, deleting temporary files, uninitializing parser libraries, etc.. .Sp \&\f(CW\*(C`Courier::Filter::Module::destroy()\*(C'\fR does nothing. Sub-classes may override this method and define clean-up behavior. .SS "Class methods" .IX Subsection "Class methods" The following class methods are provided and may be overridden: .IP "\fBwarn($text)\fR" 4 .IX Item "warn($text)" Writes a warning message to syslog. This method may also be used as an instance method. .SS "Instance methods" .IX Subsection "Instance methods" The following instance methods are provided and may be overridden: .IP "\fBconsider($message)\fR: returns \fIstring\fR, [\fIstring\fR]; throws Perl exceptions" 4 .IX Item "consider($message): returns string, [string]; throws Perl exceptions" Calls the \f(CW\*(C`match\*(C'\fR method, passing it the \f(CW$message\fR object. Returns the result of \f(CW\*(C`match\*(C'\fR, negating it beforehand if the filter module has inverse polarity. There is usually no need at all to override this method. .IP "\fBmatch($message)\fR: returns \fIstring\fR, [\fIstring\fR]; throws Perl exceptions" 4 .IX Item "match($message): returns string, [string]; throws Perl exceptions" Examines the \fBCourier::Message\fR object given as \f(CW$message\fR. Returns a so-called \&\fImatch result\fR consisting of an \s-1SMTP\s0 status response \fItext\fR, and an optional numerical \s-1SMTP\s0 status response \fIcode\fR. For details about how \fImatch results\fR are used by Courier::Filter, see \*(L"How filter modules work\*(R" in Courier::Filter::Overview and \*(L"Writing filter modules\*(R" in Courier::Filter::Overview. .Sp \&\f(CW\*(C`Courier::Filter::Module::match()\*(C'\fR does nothing and returns \fBundef\fR. Sub-classes should override this method and define their own matching rule. .IP "\fBlogger\fR: returns \fICourier::Filter::Logger\fR" 4 .IX Item "logger: returns Courier::Filter::Logger" .PD 0 .IP "\fBlogger($logger)\fR: returns \fICourier::Filter::Logger\fR" 4 .IX Item "logger($logger): returns Courier::Filter::Logger" .PD If \f(CW$logger\fR is specified, installs a new logger for this individual filter module. Returns the current (new) logger. .IP "\fBinverse\fR: returns \fIboolean\fR" 4 .IX Item "inverse: returns boolean" Returns a boolean value indicating whether the filter module is operating with inverse polarity, as set through the constructor's \f(CW\*(C`inverse\*(C'\fR option. .IP "\fBtrusting\fR: returns \fIboolean\fR" 4 .IX Item "trusting: returns boolean" Returns a boolean value indicating whether the filter module does \fInot\fR apply to trusted messages, as set through the constructor's \f(CW\*(C`trusting\*(C'\fR option. .IP "\fBtesting\fR: returns \fIboolean\fR" 4 .IX Item "testing: returns boolean" Returns a boolean value indicating whether the filter module is in testing mode, as set through the constructor's \f(CW\*(C`testing\*(C'\fR option. .IP "\fBdebugging\fR: returns \fIboolean\fR" 4 .IX Item "debugging: returns boolean" .PD 0 .IP "\fBdebugging($debugging)\fR: returns \fIboolean\fR" 4 .IX Item "debugging($debugging): returns boolean" .PD If \f(CW$debugging\fR is specified, sets the debugging mode for this individual filter module. Returns the (newly) configured debugging mode. .SH "SEE ALSO" .IX Header "SEE ALSO" Courier::Filter, Courier::Filter::Module. .PP For a list of prepared loggers that come with Courier::Filter, see \&\*(L"Bundled Courier::Filter loggers\*(R" in Courier::Filter::Overview. .PP For \s-1AVAILABILITY, SUPPORT,\s0 and \s-1LICENSE\s0 information, see Courier::Filter::Overview. .SH "AUTHOR" .IX Header "AUTHOR" Julian Mehnle