1Mail::SpamAssassin::PluUgsienr(3C)ontributed Perl DocumeMnatialt:i:oSnpamAssassin::Plugin(3)
2
3
4

NAME

6       Mail::SpamAssassin::Plugin - SpamAssassin plugin base class
7

SYNOPSIS

9   SpamAssassin configuration:
10         loadplugin MyPlugin /path/to/myplugin.pm
11
12   Perl code:
13         package MyPlugin;
14
15         use Mail::SpamAssassin::Plugin;
16         our @ISA = qw(Mail::SpamAssassin::Plugin);
17
18         sub new {
19           my ($class, $mailsa) = @_;
20
21           # the usual perlobj boilerplate to create a subclass object
22           $class = ref($class) || $class;
23           my $self = $class->SUPER::new($mailsa);
24           bless ($self, $class);
25
26           # then register an eval rule, if desired...
27           $self->register_eval_rule ("check_for_foo");
28
29           # and return the new plugin object
30           return $self;
31         }
32
33         ...methods...
34
35         1;
36

DESCRIPTION

38       This is the base class for SpamAssassin plugins; all plugins must be
39       objects that implement this class.
40
41       This class provides no-op stub methods for all the callbacks that a
42       plugin can receive.  It is expected that your plugin will override one
43       or more of these stubs to perform its actions.
44
45       SpamAssassin implements a plugin chain; each callback event is passed
46       to each of the registered plugin objects in turn.  Any plugin can call
47       "$self->inhibit_further_callbacks()" to block delivery of that event to
48       later plugins in the chain.  This is useful if the plugin has handled
49       the event, and there will be no need for later plugins to handle it as
50       well.
51
52       If you're looking to write a simple eval rule, skip straight to
53       "register_eval_rule()", below.
54

INTERFACE

56       In all the plugin APIs below, "options" refers to a reference to a hash
57       containing name-value pairs.   This is used to ensure future-
58       compatibility, in that we can add new options in future without
59       affecting objects built to an earlier version of the API.
60
61       For example, here would be how to print out the "line" item in a
62       "parse_config()" method:
63
64         sub parse_config {
65           my ($self, $opts) = @_;
66           print "MyPlugin: parse_config got ".$opts->{line}."\n";
67         }
68

METHODS

70       The following methods can be overridden by subclasses to handle events.
71
72       $plugin = MyPluginClass->new ($mailsaobject)
73           Constructor.  Plugins that need to register themselves will need to
74           define their own; the default super-class constructor will work
75           fine for plugins that just override a method.
76
77           Note that subclasses must provide the $mailsaobject to the
78           superclass constructor, like so:
79
80             my $self = $class->SUPER::new($mailsaobject);
81
82           Lifecycle note: plugins that will need to store per-scan state
83           should not store that on the Plugin object; instead this should be
84           stored on the PerMsgStatus object, see "check_start()" below.  It
85           is also likewise recommended that configuration settings be stored
86           on the Conf object; see "parse_config()".
87
88       $plugin->parse_config ( { options ... } )
89           Parse a configuration line that hasn't already been handled.
90           "options" is a reference to a hash containing these options:
91
92           line
93               The line of configuration text to parse.   This has leading and
94               trailing whitespace, and comments, removed.
95
96           key The configuration key; ie. the first "word" on the line.
97
98           value
99               The configuration value; everything after the first "word" and
100               any whitespace after that.
101
102           conf
103               The "Mail::SpamAssassin::Conf" object on which the
104               configuration data should be stored.
105
106           user_config
107               A boolean: 1 if reading a user's configuration, 0 if reading
108               the system-wide configuration files.
109
110           If the configuration line was a setting that is handled by this
111           plugin, the method implementation should call
112           "$self->inhibit_further_callbacks()".
113
114           If the setting is not handled by this plugin, the method should
115           return 0 so that a later plugin may handle it, or so that
116           SpamAssassin can output a warning message to the user if no plugin
117           understands it.
118
119           Lifecycle note: it is suggested that configuration be stored on the
120           "Mail::SpamAssassin::Conf" object in use, instead of the plugin
121           object itself.  That can be found as "$plugin->{main}->{conf}", or
122           as "conf" in the $options hash reference above.   By storing it on
123           "conf", this allows per-user and system-wide configuration
124           precedence to be dealt with correctly.
125
126       $plugin->finish_parsing_start ( { options ... } )
127           Signals that the system-wide configuration has been completely
128           read, but internal data structures are not yet created. It is
129           possible to use this hook to dynamically change the configuration
130           already read in or add new config options.
131
132           "options" is a reference to a hash containing these options:
133
134           conf
135               The "Mail::SpamAssassin::Conf" object on which the
136               configuration data should be stored.
137
138           Note: there are no guarantees that the internal data structures of
139           SpamAssassin will not change from release to release.  In
140           particular to this plugin hook, if you modify the rules data
141           structures in a third-party plugin, all bets are off until such
142           time that an API is present for modifying that configuration data.
143
144       $plugin->finish_parsing_end ( { options ... } )
145           Signals that the system-wide configuration parsing has just
146           finished, and SpamAssassin is nearly ready to check messages.
147
148           "options" is a reference to a hash containing these options:
149
150           conf
151               The "Mail::SpamAssassin::Conf" object on which the
152               configuration data should be stored.
153
154           Note: there are no guarantees that the internal data structures of
155           SpamAssassin will not change from release to release.  In
156           particular to this plugin hook, if you modify the rules data
157           structures in a third-party plugin, all bets are off until such
158           time that an API is present for modifying that configuration data.
159
160       $plugin->user_conf_parsing_start ( { options ... } )
161           Signals that the per-user configuration has been completely read,
162           but not converted to internal data structures. It is possible to
163           use this hook to dynamically change the configuration already read
164           in or add new config options.
165
166           If "allow_user_rules" is enabled in the configuration, it is
167           possible that additional rules have been added since the
168           "finish_parsing_start" plugin hook invocation was called.
169
170           conf
171               The "Mail::SpamAssassin::Conf" object on which the
172               configuration data should be stored.
173
174           Note: there are no guarantees that the internal data structures of
175           SpamAssassin will not change from release to release.  In
176           particular to this plugin hook, if you modify the rules data
177           structures in a third-party plugin, all bets are off until such
178           time that an API is present for modifying that configuration data.
179
180       $plugin->user_conf_parsing_end ( { options ... } )
181           Signals that the per-user configuration parsing has just finished,
182           and SpamAssassin is nearly ready to check messages.   If
183           "allow_user_rules" is enabled in the configuration, it is possible
184           that additional rules have been added since the
185           "finish_parsing_end" plugin hook invocation was called.
186
187           "options" is a reference to a hash containing these options:
188
189           conf
190               The "Mail::SpamAssassin::Conf" object on which the
191               configuration data should be stored.
192
193           Note: there are no guarantees that the internal data structures of
194           SpamAssassin will not change from release to release.  In
195           particular to this plugin hook, if you modify the rules data
196           structures in a third-party plugin, all bets are off until such
197           time that an API is present for modifying that configuration data.
198
199       $plugin->signal_user_changed ( { options ... } )
200           Signals that the current user has changed for a new one.
201
202           username
203               The new user's username.
204
205           user_dir
206               The new user's home directory. (equivalent to "~".)
207
208           userstate_dir
209               The new user's storage directory. (equivalent to
210               "~/.spamassassin".)
211
212       $plugin->services_authorized_for_username ( { options ... } )
213           Validates that a given username is authorized to use certain
214           services.
215
216           In order to authorize a user, the plugin should first check that it
217           can handle any of the services passed into the method and then set
218           the value for each allowed service to true (or any non-negative
219           value).
220
221           The current supported services are: bayessql
222
223           username
224               A username
225
226           services
227               Reference to a hash containing the services you want to check.
228
229               {
230
231                 'bayessql' => 0
232
233               }
234
235           conf
236               The "Mail::SpamAssassin::Conf" object on which the
237               configuration data should be stored.
238
239       $plugin->compile_now_start ( { options ... } )
240           This is called at the beginning of
241           Mail::SpamAssassin::compile_now() so plugins can do any necessary
242           initialization for multi-process SpamAssassin (such as spamd or
243           mass-check -j).
244
245           use_user_prefs
246               The value of $use_user_prefs option in compile_now().
247
248           keep_userstate
249               The value of $keep_userstate option in compile_now().
250
251       $plugin->compile_now_finish ( { options ... } )
252           This is called at the end of Mail::SpamAssassin::compile_now() so
253           plugins can do any necessary initialization for multi-process
254           SpamAssassin (such as spamd or mass-check -j).
255
256           use_user_prefs
257               The value of $use_user_prefs option in compile_now().
258
259           keep_userstate
260               The value of $keep_userstate option in compile_now().
261
262       $plugin->check_start ( { options ... } )
263           Signals that a message check operation is starting.
264
265           permsgstatus
266               The "Mail::SpamAssassin::PerMsgStatus" context object for this
267               scan.
268
269               Lifecycle note: it is recommended that rules that need to track
270               test state on a per-scan basis should store that state on this
271               object, not on the plugin object itself, since the plugin
272               object will be shared between all active scanners.
273
274               The message being scanned is accessible through the
275               "$permsgstatus->get_message()" API; there are a number of other
276               public APIs on that object, too.  See
277               "Mail::SpamAssassin::PerMsgStatus" perldoc.
278
279       $plugin->check_main ( { options ... } )
280           Signals that a message should be checked.  Note that
281           implementations of this hook should return 1.
282
283           permsgstatus
284               The "Mail::SpamAssassin::PerMsgStatus" context object for this
285               scan.
286
287       $plugin->check_tick ( { options ... } )
288           Called periodically during a message check operation.  A callback
289           set for this method is a good place to run through an event loop
290           dealing with network events triggered in a "parse_metadata" method,
291           for example.
292
293           permsgstatus
294               The "Mail::SpamAssassin::PerMsgStatus" context object for this
295               scan.
296
297       $plugin->check_post_dnsbl ( { options ... } )
298           Called after the DNSBL results have been harvested.  This is a good
299           place to harvest your own asynchronously-started network lookups.
300
301           permsgstatus
302               The "Mail::SpamAssassin::PerMsgStatus" context object for this
303               scan.
304
305       $plugin->check_post_learn ( { options ... } )
306           Called after auto-learning may (or may not) have taken place.  If
307           you wish to perform additional learning, whether or not auto-
308           learning happens, this is the place to do it.
309
310           permsgstatus
311               The "Mail::SpamAssassin::PerMsgStatus" context object for this
312               scan.
313
314       $plugin->check_end ( { options ... } )
315           Signals that a message check operation has just finished, and the
316           results are about to be returned to the caller.
317
318           permsgstatus
319               The "Mail::SpamAssassin::PerMsgStatus" context object for this
320               scan.  The current score, names of rules that hit, etc. can be
321               retrieved using the public APIs on this object.
322
323       $plugin->finish_tests ( { options ... } )
324           Called via "Mail::SpamAssassin::finish".  This should clear up any
325           tests that a plugin has added to the namespace.
326
327           In certain circumstances, plugins may find it useful to compile
328           perl functions from the ruleset, on the fly.  It is important to
329           remove these once the "Mail::SpamAssassin" object is deleted,
330           however, and this API allows this.
331
332           Each plugin is responsible for its own generated perl functions.
333
334           conf
335               The "Mail::SpamAssassin::Conf" object on which the
336               configuration data should be stored.
337
338           See also the "register_generated_rule_method" helper API, below.
339
340       $plugin->extract_metadata ( { options ... } )
341           Signals that a message is being mined for metadata.  Some plugins
342           may wish to add their own metadata as well.
343
344           msg The "Mail::SpamAssassin::Message" object for this message.
345
346       $plugin->parsed_metadata ( { options ... } )
347           Signals that a message's metadata has been parsed, and can now be
348           accessed by the plugin.
349
350           permsgstatus
351               The "Mail::SpamAssassin::PerMsgStatus" context object for this
352               scan.
353
354       $plugin->start_rules ( { options ... } )
355           Called before testing a set of rules of a given type and priority.
356
357           permsgstatus
358               The "Mail::SpamAssassin::PerMsgStatus" context object for this
359               scan.
360
361           ruletype
362               The type of the rules about to be performed.
363
364           priority
365               The priority level of the rules about to be performed.
366
367       $plugin->hit_rule ( { options ... } )
368           Called when a rule fires.
369
370           permsgstatus
371               The "Mail::SpamAssassin::PerMsgStatus" context object for this
372               scan.
373
374           ruletype
375               The type of the rule that fired.
376
377           rulename
378               The name of the rule that fired.
379
380           score
381               The rule's score in the active scoreset.
382
383       $plugin->ran_rule ( { options ... } )
384           Called after a rule has been tested, whether or not it fired.  When
385           the rule fires, the hit_rule callback is always called before this.
386
387           permsgstatus
388               The "Mail::SpamAssassin::PerMsgStatus" context object for this
389               scan.
390
391           ruletype
392               The type of the rule that was tested.
393
394           rulename
395               The name of the rule that was tested.
396
397       $plugin->autolearn_discriminator ( { options ... } )
398           Control whether a just-scanned message should be learned as either
399           spam or ham.   This method should return one of 1 to learn the
400           message as spam, 0 to learn as ham, or "undef" to not learn from
401           the message at all.
402
403           permsgstatus
404               The "Mail::SpamAssassin::PerMsgStatus" context object for this
405               scan.
406
407       $plugin->autolearn ( { options ... } )
408           Signals that a message is about to be auto-learned as either ham or
409           spam.
410
411           permsgstatus
412               The "Mail::SpamAssassin::PerMsgStatus" context object for this
413               scan.
414
415           isspam
416               1 if the message is spam, 0 if ham.
417
418       $plugin->per_msg_finish ( { options ... } )
419           Signals that a "Mail::SpamAssassin::PerMsgStatus" object is being
420           destroyed, and any per-scan context held on that object by this
421           plugin should be destroyed as well.
422
423           Normally, any member variables on the "PerMsgStatus" object will be
424           cleaned up automatically -- but if your plugin has made a circular
425           reference on that object, this is the place to break them so that
426           garbage collection can operate correctly.
427
428           permsgstatus
429               The "Mail::SpamAssassin::PerMsgStatus" context object for this
430               scan.
431
432       $plugin->have_shortcircuited ( { options ... } )
433           Has the current scan operation 'short-circuited'?  In other words,
434           can further scanning be skipped, since the message is already
435           definitively classified as either spam or ham?
436
437           Plugins should return 0 to indicate that scanning should continue,
438           or 1 to indicate that short-circuiting has taken effect.
439
440           permsgstatus
441               The "Mail::SpamAssassin::PerMsgStatus" context object for this
442               scan.
443
444       $plugin->bayes_learn ( { options ... } )
445           Called at the end of a bayes learn operation.
446
447           This phase is the best place to map the raw (original) token value
448           to the SHA1 hashed value.
449
450           toksref
451               Reference to hash returned by call to tokenize.  The hash takes
452               the format of:
453
454                 {
455                   'SHA1 Hash Value' => 'raw (original) value',
456                   ...
457                 }
458
459               NOTE: This data structure has changed since it was originally
460               introduced in version 3.0.0.  The values are no longer perl
461               anonymous hashes, they are a single string containing the raw
462               token value.  You can test for backwards compatibility by
463               checking to see if the value for a key is a reference to a perl
464               HASH, for instance:
465
466               if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
467
468               If it is, then you are using the old interface, otherwise you
469               are using the current interface.
470
471           isspam
472               Boolean value stating what flavor of message the tokens
473               represent, if true then message was specified as spam, false is
474               nonspam.  Note, when function is scan then isspam value is not
475               valid.
476
477           msgid
478               Generated message id of the message just learned.
479
480           msgatime
481               Received date of the current message or current time if
482               received date could not be determined.  In addition, if the
483               receive date is more than 24 hrs into the future it will be
484               reset to current datetime.
485
486       $plugin->bayes_forget ( { options ... } )
487           Called at the end of a bayes forget operation.
488
489           toksref
490               Reference to hash returned by call to tokenize.  See
491               bayes_learn documentation for additional information on the
492               format.
493
494           isspam
495               Boolean value stating what flavor of message the tokens
496               represent, if true then message was specified as spam, false is
497               nonspam.  Note, when function is scan then isspam value is not
498               valid.
499
500           msgid
501               Generated message id of the message just forgotten.
502
503       $plugin->bayes_scan ( { options ... } )
504           Called at the end of a bayes scan operation.  NOTE: Will not be
505           called in case of error or if the message is otherwise skipped.
506
507           toksref
508               Reference to hash returned by call to tokenize.  See
509               bayes_learn documentation for additional information on the
510               format.
511
512           probsref
513               Reference to hash of calculated probabilities for tokens found
514               in the database.
515
516                 {
517                   'SHA1 Hash Value' => {
518                           'prob' => 'calculated probability',
519                           'spam_count' => 'Total number of spam msgs w/ token',
520                           'ham_count' => 'Total number of ham msgs w/ token',
521                           'atime' => 'Atime value for token in database'
522                         }
523                 }
524
525           score
526               Score calculated for this particular message.
527
528           msgatime
529               Calculated atime of the message just learned, note it may have
530               been adjusted if it was determined to be too far into the
531               future.
532
533           significant_tokens
534               Array ref of the tokens found to be significant in determining
535               the score for this message.
536
537       $plugin->plugin_report ( { options ... } )
538           Called if the message is to be reported as spam.  If the reporting
539           system is available, the variable
540           "$options->{report}->report_available}" should be set to 1; if the
541           reporting system successfully reported the message, the variable
542           "$options->{report}->report_return}" should be set to 1.
543
544           report
545               Reference to the Reporter object ("$options->{report}" in the
546               paragraph above.)
547
548           text
549               Reference to a markup removed copy of the message in scalar
550               string format.
551
552           msg Reference to the original message object.
553
554       $plugin->plugin_revoke ( { options ... } )
555           Called if the message is to be reported as ham (revokes a spam
556           report). If the reporting system is available, the variable
557           "$options->{revoke}->revoke_available}" should be set to 1; if the
558           reporting system successfully revoked the message, the variable
559           "$options->{revoke}->revoke_return}" should be set to 1.
560
561           revoke
562               Reference to the Reporter object ("$options->{revoke}" in the
563               paragraph above.)
564
565           text
566               Reference to a markup removed copy of the message in scalar
567               string format.
568
569           msg Reference to the original message object.
570
571       $plugin->whitelist_address( { options ... } )
572           Called when a request is made to add an address to a persistent
573           address list.
574
575           address
576               Address you wish to add.
577
578           cli_p
579               Indicate if the call is being made from a command line
580               interface.
581
582       $plugin->blacklist_address( { options ... } )
583           Called when a request is made to add an address to a persistent
584           address list.
585
586           address
587               Address you wish to add.
588
589           cli_p
590               Indicate if the call is being made from a command line
591               interface.
592
593       $plugin->remove_address( { options ... } )
594           Called when a request is made to remove an address to a persistent
595           address list.
596
597           address
598               Address you wish to remove.
599
600           cli_p
601               Indicate if the call is being made from a command line
602               interface.
603
604       $plugin->spamd_child_init ()
605           Called when a new child starts up under spamd.
606
607       $plugin->log_scan_result ( { options ... } )
608           Called when spamd has completed scanning a message.  Currently,
609           only spamd calls this API.
610
611           result
612               The 'result: ...' line for this scan.  Format is as described
613               at http://wiki.apache.org/spamassassin/SpamdSyslogFormat.
614
615       $plugin->spamd_child_post_connection_close ()
616           Called when child returns from handling a connection.
617
618           If there was an accept failure, the child will die and this code
619           will not be called.
620
621       $plugin->finish ()
622           Called when the "Mail::SpamAssassin" object is destroyed.
623
624       $plugin->learner_new ()
625           Used to support human-trained probabilistic classifiers like the
626           BAYES_* ruleset.  Called when a new "Mail::SpamAssassin::Bayes"
627           object has been created; typically when a new user's scan is about
628           to start.
629
630       $plugin->learn_message ()
631           Train the classifier with a training message.
632
633           isspam
634               1 if the message is spam, 0 if it's non-spam.
635
636           msg The message's "Mail::SpamAssassin::Message" object.
637
638           id  An optional message-identification string, used internally to
639               tag the message.  If it is "undef", one will be generated.  It
640               should be unique to that message.
641
642       $plugin->forget_message ()
643           Tell the classifier to 'forget' its training about a specific
644           message.
645
646           msg The message's "Mail::SpamAssassin::Message" object.
647
648           id  An optional message-identification string, used internally to
649               tag the message.  If it is "undef", one will be generated.  It
650               should be unique to that message.
651
652       $plugin->learner_sync ()
653           Tell the classifier to 'sync' any pending changes against the
654           current user's training database.  This is called by "sa-learn
655           --sync".
656
657           If you do not need to implement these for your classifier, create
658           an implementation that just contains "return 1".
659
660       $plugin->learner_expire_old_training ()
661           Tell the classifier to perform infrequent, time-consuming cleanup
662           of the current user's training database.  This is called by
663           "sa-learn --force-expire".
664
665           If you do not need to implement these for your classifier, create
666           an implementation that just contains "return 1".
667
668       $plugin->learner_is_scan_available ()
669           Should return 1 if it is possible to use the current user's
670           training data for a message-scan operation, or 0 otherwise.
671
672       $plugin->learner_dump_database ()
673           Dump information about the current user's training data to
674           "stdout".  This is called by "sa-learn --dump".
675
676           magic
677               Set to 1 if "magic" name-value metadata should be dumped.
678
679           toks
680               Set to 1 if the database of tokens should be dumped.
681
682           regex
683               Either "undef" to dump all tokens, or a value which specifies a
684               regular expression subset of the tokens to dump.
685
686       $plugin->learner_close ()
687           Close any open databases.
688
689           quiet
690               Set to 1 if warning messages should be suppressed.
691

HELPER APIS

693       These methods provide an API for plugins to register themselves to
694       receive specific events, or control the callback chain behaviour.
695
696       $plugin->register_eval_rule ($nameofevalsub)
697           Plugins that implement an eval test will need to call this, so that
698           SpamAssassin calls into the object when that eval test is
699           encountered.  See the REGISTERING EVAL RULES section for full
700           details.
701
702       $plugin->register_generated_rule_method ($nameofsub)
703           In certain circumstances, plugins may find it useful to compile
704           perl functions from the ruleset, on the fly.  It is important to
705           remove these once the "Mail::SpamAssassin" object is deleted,
706           however, and this API allows this.
707
708           Once the method $nameofsub has been generated, call this API with
709           the name of the method (including full package scope).  This
710           indicates that it's a temporary piece of generated code, built from
711           the SpamAssassin ruleset, and when "Mail::SpamAssassin::finish()"
712           is called, the method will be destroyed.
713
714           This API was added in SpamAssassin 3.2.0.
715
716       $plugin->register_method_priority($methodname, $priority)
717           Indicate that the method named $methodname on the current object
718           has a callback priority of $priority.
719
720           This is used by the plugin handler to determine the relative order
721           of callbacks; plugins with lower-numbered priorities are called
722           before plugins with higher-numbered priorities.  Each method can
723           have a different priority value.  The default value is 0.  The
724           ordering of callbacks to methods with equal priority is undefined.
725
726           Typically, you only need to worry about this if you need to ensure
727           your plugin's method is called before another plugin's
728           implementation of that method.  It should be called from your
729           plugin's constructor.
730
731           This API was added in SpamAssassin 3.2.0.
732
733       $plugin->inhibit_further_callbacks()
734           Tells the plugin handler to inhibit calling into other plugins in
735           the plugin chain for the current callback.  Frequently used when
736           parsing configuration settings using "parse_config()".
737

LOGGING

739       Mail::SpamAssassin::Plugin::dbg($message)
740           Output a debugging message $message, if the SpamAssassin object is
741           running with debugging turned on.
742
743           NOTE: This function is not available in the package namespace of
744           general plugins and can't be called via $self->dbg().  If a plugin
745           wishes to output debug information, it should call
746           "Mail::SpamAssassin::Plugin::dbg($msg)".
747
748       Mail::SpamAssassin::Plugin::info($message)
749           Output an informational message $message, if the SpamAssassin
750           object is running with informational messages turned on.
751
752           NOTE: This function is not available in the package namespace of
753           general plugins and can't be called via $self->info().  If a plugin
754           wishes to output debug information, it should call
755           "Mail::SpamAssassin::Plugin::info($msg)".
756
757           In general, it is better for plugins to use the
758           "Mail::SpamAssassin::Logger" module to import "dbg" and "info"
759           directly, like so:
760
761             use Mail::SpamAssassin::Logger;
762             dbg("some message");
763             info("some other message");
764

REGISTERING EVAL RULES

766       Plugins that implement an eval test must register the methods that can
767       be called from rules in the configuration files, in the plugin class'
768       constructor.
769
770       For example,
771
772         $plugin->register_eval_rule ('check_for_foo')
773
774       will cause "$plugin->check_for_foo()" to be called for this
775       SpamAssassin rule:
776
777         header   FOO_RULE     eval:check_for_foo()
778
779       Note that eval rules are passed the following arguments:
780
781       - The plugin object itself
782       - The "Mail::SpamAssassin::PerMsgStatus" object calling the rule
783       - standard arguments for the rule type in use
784       - any and all arguments as specified in the configuration file
785
786       In other words, the eval test method should look something like this:
787
788         sub check_for_foo {
789           my ($self, $permsgstatus, ...arguments...) = @_;
790           ...code returning 0 or 1
791         }
792
793       Note that the headers can be accessed using the "get()" method on the
794       "Mail::SpamAssassin::PerMsgStatus" object, and the body by
795       "get_decoded_stripped_body_text_array()" and other similar methods.
796       Similarly, the "Mail::SpamAssassin::Conf" object holding the current
797       configuration may be accessed through "$permsgstatus->{main}->{conf}".
798
799       The eval rule should return 1 for a hit, or 0 if the rule is not hit.
800
801       State for a single message being scanned should be stored on the
802       $permsgstatus object, not on the $self object, since $self persists
803       between scan operations.  See the 'lifecycle note' on the
804       "check_start()" method above.
805

STANDARD ARGUMENTS FOR RULE TYPES

807       Plugins will be called with the same arguments as a standard EvalTest.
808       Different rule types receive different information by default:
809
810       - header tests: no extra arguments
811       - body tests: fully rendered message as array reference
812       - rawbody tests: fully decoded message as array reference
813       - full tests: pristine message as scalar reference
814
815       The configuration file arguments will be passed in after the standard
816       arguments.
817

BACKWARDS COMPATIBILITY

819       Note that if you write a plugin and need to determine if a particular
820       helper method is supported on "Mail::SpamAssassin::Plugin", you can do
821       this:
822
823           if ($self->can("name_of_method")) {
824             eval {
825               $self->name_of_method();        # etc.
826             }
827           } else {
828             # take fallback action
829           }
830
831       The same applies for the public APIs on objects of other types, such as
832       "Mail::SpamAssassin::PerMsgStatus".
833

SEE ALSO

835       "Mail::SpamAssassin"
836
837       "Mail::SpamAssassin::PerMsgStatus"
838
839       http://wiki.apache.org/spamassassin/PluginWritingTips
840
841       http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163
842
843
844
845perl v5.10.1                      2010-03-16     Mail::SpamAssassin::Plugin(3)
Impressum