File Coverage

blib/lib/Mail/SpamAssassin/Plugin.pm
Criterion Covered Total %
statement 27 34 79.4
branch 1 2 50.0
condition 1 3 33.3
subroutine 8 11 72.7
pod 6 6 100.0
total 43 56 76.7


line stmt bran cond sub pod time code
1             # <@LICENSE>
2             # Licensed to the Apache Software Foundation (ASF) under one or more
3             # contributor license agreements. See the NOTICE file distributed with
4             # this work for additional information regarding copyright ownership.
5             # The ASF licenses this file to you under the Apache License, Version 2.0
6             # (the "License"); you may not use this file except in compliance with
7             # the License. You may obtain a copy of the License at:
8             #
9             # http://www.apache.org/licenses/LICENSE-2.0
10             #
11             # Unless required by applicable law or agreed to in writing, software
12             # distributed under the License is distributed on an "AS IS" BASIS,
13             # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14             # See the License for the specific language governing permissions and
15             # limitations under the License.
16             # </@LICENSE>
17              
18             =head1 NAME
19              
20             Mail::SpamAssassin::Plugin - SpamAssassin plugin base class
21              
22             =head1 SYNOPSIS
23              
24             =head2 SpamAssassin configuration:
25              
26             loadplugin MyPlugin /path/to/myplugin.pm
27              
28             =head2 Perl code:
29              
30             package MyPlugin;
31              
32             use Mail::SpamAssassin::Plugin;
33             our @ISA = qw(Mail::SpamAssassin::Plugin);
34              
35             sub new {
36             my ($class, $mailsa) = @_;
37            
38             # the usual perlobj boilerplate to create a subclass object
39             $class = ref($class) || $class;
40             my $self = $class->SUPER::new($mailsa);
41             bless ($self, $class);
42            
43             # then register an eval rule, if desired...
44             $self->register_eval_rule ("check_for_foo");
45              
46             # and return the new plugin object
47             return $self;
48             }
49              
50             ...methods...
51              
52             1;
53              
54             =head1 DESCRIPTION
55              
56             This is the base class for SpamAssassin plugins; all plugins must be objects
57             that implement this class.
58              
59             This class provides no-op stub methods for all the callbacks that a plugin
60             can receive. It is expected that your plugin will override one or more
61             of these stubs to perform its actions.
62              
63             SpamAssassin implements a plugin chain; each callback event is passed to each
64             of the registered plugin objects in turn. Any plugin can call
65             C<$self-E<gt>inhibit_further_callbacks()> to block delivery of that event to
66             later plugins in the chain. This is useful if the plugin has handled the
67             event, and there will be no need for later plugins to handle it as well.
68              
69             If you're looking to write a simple eval rule, skip straight to
70             C<register_eval_rule()>, below.
71              
72             =head1 INTERFACE
73              
74             In all the plugin APIs below, C<options> refers to a reference to a hash
75             containing name-value pairs. This is used to ensure future-compatibility, in
76             that we can add new options in future without affecting objects built to an
77             earlier version of the API.
78              
79             For example, here would be how to print out the C<line> item in a
80             C<parse_config()> method:
81              
82             sub parse_config {
83             my ($self, $opts) = @_;
84             print "MyPlugin: parse_config got ".$opts->{line}."\n";
85             }
86              
87             =head1 METHODS
88              
89             The following methods can be overridden by subclasses to handle events.
90              
91             =over 4
92              
93             =cut
94              
95             package Mail::SpamAssassin::Plugin;
96              
97 40     40   326 use Mail::SpamAssassin;
  40         112  
  40         1402  
98 40     40   288 use Mail::SpamAssassin::Logger;
  40         109  
  40         2720  
99              
100 40     40   359 use strict;
  40         129  
  40         1229  
101 40     40   261 use warnings;
  40         143  
  40         1967  
102             # use bytes;
103 40     40   326 use re 'taint';
  40         108  
  40         20274  
104              
105             our @ISA = qw();
106             #Removed $VERSION per BUG 6422
107             #$VERSION = 'bogus';
108              
109             ###########################################################################
110              
111             =item $plugin = MyPluginClass->new ($mailsaobject)
112              
113             Constructor. Plugins that need to register themselves will need to
114             define their own; the default super-class constructor will work fine
115             for plugins that just override a method.
116              
117             Note that subclasses must provide the C<$mailsaobject> to the
118             superclass constructor, like so:
119              
120             my $self = $class->SUPER::new($mailsaobject);
121              
122             Lifecycle note: plugins that will need to store per-scan state should not store
123             that on the Plugin object; instead this should be stored on the PerMsgStatus
124             object, see C<check_start()> below. It is also likewise recommended that
125             configuration settings be stored on the Conf object; see C<parse_config()>.
126              
127             =cut
128              
129             sub new {
130 1793     1793 1 3369 my $class = shift;
131 1793         2512 my $mailsaobject = shift;
132 1793   33     5716 $class = ref($class) || $class;
133              
134 1793 50       3697 if (!defined $mailsaobject) {
135 0         0 die "plugin: usage: Mail::SpamAssassin::Plugin::new(class,mailsaobject)";
136             }
137              
138 1793         5362 my $self = {
139             main => $mailsaobject,
140             _inhibit_further_callbacks => 0
141             };
142 1793         3490 bless ($self, $class);
143 1793         4109 $self;
144             }
145              
146             # ---------------------------------------------------------------------------
147             # now list the supported methods we will call into. NOTE: we don't have
148             # to implement them here, since the plugin can use "can()" to introspect
149             # the object and determine if it's capable of calling the method anyway.
150             # Nifty!
151              
152             =item $plugin->parse_config ( { options ... } )
153              
154             Parse a configuration line that hasn't already been handled. C<options>
155             is a reference to a hash containing these options:
156              
157             =over 4
158              
159             =item line
160              
161             The line of configuration text to parse. This has leading and trailing
162             whitespace, and comments, removed.
163              
164             =item key
165              
166             The configuration key; ie. the first "word" on the line.
167              
168             =item value
169              
170             The configuration value; everything after the first "word" and
171             any whitespace after that.
172              
173             =item conf
174              
175             The C<Mail::SpamAssassin::Conf> object on which the configuration
176             data should be stored.
177              
178             =item user_config
179              
180             A boolean: C<1> if reading a user's configuration, C<0> if reading the
181             system-wide configuration files.
182              
183             =back
184              
185             If the configuration line was a setting that is handled by this plugin, the
186             method implementation should call C<$self-E<gt>inhibit_further_callbacks()>.
187              
188             If the setting is not handled by this plugin, the method should return C<0> so
189             that a later plugin may handle it, or so that SpamAssassin can output a warning
190             message to the user if no plugin understands it.
191              
192             Lifecycle note: it is suggested that configuration be stored on the
193             C<Mail::SpamAssassin::Conf> object in use, instead of the plugin object itself.
194             That can be found as C<$plugin-E<gt>{main}-E<gt>{conf}>, or as "conf" in the
195             C<$options> hash reference above. By storing it on C<conf>, this allows
196             per-user and system-wide configuration precedence to be dealt with correctly.
197              
198             =item $plugin->finish_parsing_start ( { options ... } )
199              
200             Signals that the system-wide configuration has been completely read,
201             but internal data structures are not yet created. It is possible to
202             use this hook to dynamically change the configuration already read in
203             or add new config options.
204              
205             C<options> is a reference to a hash containing these options:
206              
207             =over 4
208              
209             =item conf
210              
211             The C<Mail::SpamAssassin::Conf> object on which the configuration
212             data should be stored.
213              
214             =back
215              
216             Note: there are no guarantees that the internal data structures of
217             SpamAssassin will not change from release to release. In particular to
218             this plugin hook, if you modify the rules data structures in a
219             third-party plugin, all bets are off until such time that an API is
220             present for modifying that configuration data.
221              
222             =item $plugin->finish_parsing_end ( { options ... } )
223              
224             Signals that the system-wide configuration parsing has just finished, and
225             SpamAssassin is nearly ready to check messages.
226              
227             C<options> is a reference to a hash containing these options:
228              
229             =over 4
230              
231             =item conf
232              
233             The C<Mail::SpamAssassin::Conf> object on which the configuration
234             data should be stored.
235              
236             =back
237              
238             Note: there are no guarantees that the internal data structures of
239             SpamAssassin will not change from release to release. In particular to
240             this plugin hook, if you modify the rules data structures in a
241             third-party plugin, all bets are off until such time that an API is
242             present for modifying that configuration data.
243              
244             =item $plugin->user_conf_parsing_start ( { options ... } )
245              
246             Signals that the per-user configuration has been completely read, but
247             not converted to internal data structures. It is possible to use this
248             hook to dynamically change the configuration already read in or add
249             new config options.
250              
251             If C<allow_user_rules> is enabled in the configuration, it is possible
252             that additional rules have been added since the C<finish_parsing_start>
253             plugin hook invocation was called.
254              
255             =over 4
256              
257             =item conf
258              
259             The C<Mail::SpamAssassin::Conf> object on which the configuration
260             data should be stored.
261              
262             =back
263              
264             Note: there are no guarantees that the internal data structures of
265             SpamAssassin will not change from release to release. In particular to
266             this plugin hook, if you modify the rules data structures in a
267             third-party plugin, all bets are off until such time that an API is
268             present for modifying that configuration data.
269              
270             =item $plugin->user_conf_parsing_end ( { options ... } )
271              
272             Signals that the per-user configuration parsing has just finished, and
273             SpamAssassin is nearly ready to check messages. If C<allow_user_rules> is
274             enabled in the configuration, it is possible that additional rules have been
275             added since the C<finish_parsing_end> plugin hook invocation was called.
276              
277             C<options> is a reference to a hash containing these options:
278              
279             =over 4
280              
281             =item conf
282              
283             The C<Mail::SpamAssassin::Conf> object on which the configuration
284             data should be stored.
285              
286             =back
287              
288             Note: there are no guarantees that the internal data structures of
289             SpamAssassin will not change from release to release. In particular to
290             this plugin hook, if you modify the rules data structures in a
291             third-party plugin, all bets are off until such time that an API is
292             present for modifying that configuration data.
293              
294             =item $plugin->signal_user_changed ( { options ... } )
295              
296             Signals that the current user has changed for a new one.
297              
298             =over 4
299              
300             =item username
301              
302             The new user's username.
303              
304             =item user_dir
305              
306             The new user's home directory. (equivalent to C<~>.)
307              
308             =item userstate_dir
309              
310             The new user's storage directory. (equivalent to C<~/.spamassassin>.)
311              
312             =back
313              
314             =item $plugin->services_authorized_for_username ( { options ... } )
315              
316             Validates that a given username is authorized to use certain services.
317              
318             In order to authorize a user, the plugin should first check that it can
319             handle any of the services passed into the method and then set the value
320             for each allowed service to true (or any non-negative value).
321              
322             The current supported services are: bayessql
323              
324             =over 4
325              
326             =item username
327              
328             A username
329              
330             =item services
331              
332             Reference to a hash containing the services you want to check.
333              
334             {
335              
336             'bayessql' => 0
337              
338             }
339              
340             =item conf
341              
342             The C<Mail::SpamAssassin::Conf> object on which the configuration
343             data should be stored.
344              
345             =back
346              
347             =item $plugin->compile_now_start ( { options ... } )
348              
349             This is called at the beginning of Mail::SpamAssassin::compile_now() so
350             plugins can do any necessary initialization for multi-process
351             SpamAssassin (such as spamd or mass-check -j).
352              
353             =over 4
354              
355             =item use_user_prefs
356              
357             The value of $use_user_prefs option in compile_now().
358              
359             =item keep_userstate
360              
361             The value of $keep_userstate option in compile_now().
362              
363             =back
364              
365             =item $plugin->compile_now_finish ( { options ... } )
366              
367             This is called at the end of Mail::SpamAssassin::compile_now() so
368             plugins can do any necessary initialization for multi-process
369             SpamAssassin (such as spamd or mass-check -j).
370              
371             =over 4
372              
373             =item use_user_prefs
374              
375             The value of $use_user_prefs option in compile_now().
376              
377             =item keep_userstate
378              
379             The value of $keep_userstate option in compile_now().
380              
381             =back
382              
383             =item $plugin->check_start ( { options ... } )
384              
385             Signals that a message check operation is starting.
386              
387             =over 4
388              
389             =item permsgstatus
390              
391             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
392              
393             Lifecycle note: it is recommended that rules that need to track test state on a
394             per-scan basis should store that state on this object, not on the plugin object
395             itself, since the plugin object will be shared between all active scanners.
396              
397             The message being scanned is accessible through the
398             C<$permsgstatus-E<gt>get_message()> API; there are a number of other public
399             APIs on that object, too. See C<Mail::SpamAssassin::PerMsgStatus> perldoc.
400              
401             =back
402              
403             =item $plugin->check_main ( { options ... } )
404              
405             Signals that a message should be checked. Note that implementations of
406             this hook should return C<1>.
407              
408             =over 4
409              
410             =item permsgstatus
411              
412             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
413              
414             =back
415              
416             =item $plugin->check_tick ( { options ... } )
417              
418             Called periodically during a message check operation. A callback set for
419             this method is a good place to run through an event loop dealing with
420             network events triggered in a C<parse_metadata> method, for example.
421              
422             =over 4
423              
424             =item permsgstatus
425              
426             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
427              
428             =back
429              
430             =item $plugin->check_post_dnsbl ( { options ... } )
431              
432             Called after the DNSBL results have been harvested. This is a good
433             place to harvest your own asynchronously-started network lookups.
434              
435             =over 4
436              
437             =item permsgstatus
438              
439             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
440              
441             =back
442              
443             =item $plugin->check_post_learn ( { options ... } )
444              
445             Called after auto-learning may (or may not) have taken place. If you
446             wish to perform additional learning, whether or not auto-learning
447             happens, this is the place to do it.
448              
449             =over 4
450              
451             =item permsgstatus
452              
453             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
454              
455             =back
456              
457             =item $plugin->check_end ( { options ... } )
458              
459             Signals that a message check operation has just finished, and the
460             results are about to be returned to the caller.
461              
462             =over 4
463              
464             =item permsgstatus
465              
466             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
467             The current score, names of rules that hit, etc. can be retrieved
468             using the public APIs on this object.
469              
470             =back
471              
472             =item $plugin->finish_tests ( { options ... } )
473              
474             Called via C<Mail::SpamAssassin::finish>. This should clear up any tests that
475             a plugin has added to the namespace.
476              
477             In certain circumstances, plugins may find it useful to compile
478             perl functions from the ruleset, on the fly. It is important to
479             remove these once the C<Mail::SpamAssassin> object is deleted,
480             however, and this API allows this.
481              
482             Each plugin is responsible for its own generated perl functions.
483              
484             =over 4
485              
486             =item conf
487              
488             The C<Mail::SpamAssassin::Conf> object on which the configuration
489             data should be stored.
490              
491             =back
492              
493             See also the C<register_generated_rule_method> helper API, below.
494              
495             =item $plugin->extract_metadata ( { options ... } )
496              
497             Signals that a message is being mined for metadata. Some plugins may wish
498             to add their own metadata as well.
499              
500             =over 4
501              
502             =item msg
503              
504             The C<Mail::SpamAssassin::Message> object for this message.
505              
506             =item permsgstatus
507              
508             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
509              
510             =back
511              
512             =item $plugin->parsed_metadata ( { options ... } )
513              
514             Signals that a message's metadata has been parsed, and can now be
515             accessed by the plugin.
516              
517             =over 4
518              
519             =item permsgstatus
520              
521             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
522              
523             =back
524              
525             =item $plugin->start_rules ( { options ... } )
526              
527             Called before testing a set of rules of a given type and priority.
528              
529             =over 4
530              
531             =item permsgstatus
532              
533             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
534              
535             =item ruletype
536              
537             The type of the rules about to be performed.
538              
539             =item priority
540              
541             The priority level of the rules about to be performed.
542              
543             =back
544              
545             =item $plugin->hit_rule ( { options ... } )
546              
547             Called when a rule fires.
548              
549             =over 4
550              
551             =item permsgstatus
552              
553             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
554              
555             =item ruletype
556              
557             The type of the rule that fired.
558              
559             =item rulename
560              
561             The name of the rule that fired.
562              
563             =item score
564              
565             The rule's score in the active scoreset.
566              
567             =back
568              
569             =item $plugin->ran_rule ( { options ... } )
570              
571             Called after a rule has been tested, whether or not it fired. When the
572             rule fires, the hit_rule callback is always called before this.
573              
574             =over 4
575              
576             =item permsgstatus
577              
578             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
579              
580             =item ruletype
581              
582             The type of the rule that was tested.
583              
584             =item rulename
585              
586             The name of the rule that was tested.
587              
588             =back
589              
590             =item $plugin->autolearn_discriminator ( { options ... } )
591              
592             Control whether a just-scanned message should be learned as either
593             spam or ham. This method should return one of C<1> to learn
594             the message as spam, C<0> to learn as ham, or C<undef> to not
595             learn from the message at all.
596              
597             =over 4
598              
599             =item permsgstatus
600              
601             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
602              
603             =back
604              
605             =item $plugin->autolearn ( { options ... } )
606              
607             Signals that a message is about to be auto-learned as either ham or spam.
608              
609             =over 4
610              
611             =item permsgstatus
612              
613             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
614              
615             =item isspam
616              
617             C<1> if the message is spam, C<0> if ham.
618              
619             =back
620              
621             =item $plugin->per_msg_finish ( { options ... } )
622              
623             Signals that a C<Mail::SpamAssassin::PerMsgStatus> object is being
624             destroyed, and any per-scan context held on that object by this
625             plugin should be destroyed as well.
626              
627             Normally, any member variables on the C<PerMsgStatus> object will be cleaned up
628             automatically -- but if your plugin has made a circular reference on that
629             object, this is the place to break them so that garbage collection can operate
630             correctly.
631              
632             =over 4
633              
634             =item permsgstatus
635              
636             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
637              
638             =back
639              
640              
641             =item $plugin->have_shortcircuited ( { options ... } )
642              
643             Has the current scan operation 'short-circuited'? In other words, can
644             further scanning be skipped, since the message is already definitively
645             classified as either spam or ham?
646              
647             Plugins should return C<0> to indicate that scanning should continue,
648             or C<1> to indicate that short-circuiting has taken effect.
649              
650             =over 4
651              
652             =item permsgstatus
653              
654             The C<Mail::SpamAssassin::PerMsgStatus> context object for this scan.
655              
656             =back
657              
658             =item $plugin->bayes_learn ( { options ... } )
659              
660             Called at the end of a bayes learn operation.
661              
662             This phase is the best place to map the raw (original) token value
663             to the SHA1 hashed value.
664              
665             =over 4
666              
667             =item toksref
668              
669             Reference to hash returned by call to tokenize. The hash takes the
670             format of:
671              
672             {
673             'SHA1 Hash Value' => 'raw (original) value',
674             ...
675             }
676              
677             NOTE: This data structure has changed since it was originally introduced
678             in version 3.0.0. The values are no longer perl anonymous hashes, they
679             are a single string containing the raw token value. You can test for
680             backward compatibility by checking to see if the value for a key is a
681             reference to a perl HASH, for instance:
682              
683             if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
684              
685             If it is, then you are using the old interface, otherwise you are using
686             the current interface.
687              
688             =item isspam
689              
690             Boolean value stating what flavor of message the tokens represent, if
691             true then message was specified as spam, false is nonspam. Note, when
692             function is scan then isspam value is not valid.
693              
694             =item msgid
695              
696             Generated message id of the message just learned.
697              
698             =item msgatime
699              
700             Received date of the current message or current time if received date
701             could not be determined. In addition, if the receive date is more than
702             24 hrs into the future it will be reset to current datetime.
703              
704             =back
705              
706             =item $plugin->bayes_forget ( { options ... } )
707              
708             Called at the end of a bayes forget operation.
709              
710             =over 4
711              
712             =item toksref
713              
714             Reference to hash returned by call to tokenize. See bayes_learn
715             documentation for additional information on the format.
716              
717             =item isspam
718              
719             Boolean value stating what flavor of message the tokens represent, if
720             true then message was specified as spam, false is nonspam. Note, when
721             function is scan then isspam value is not valid.
722              
723             =item msgid
724              
725             Generated message id of the message just forgotten.
726              
727             =back
728              
729             =item $plugin->bayes_scan ( { options ... } )
730              
731             Called at the end of a bayes scan operation. NOTE: Will not be
732             called in case of error or if the message is otherwise skipped.
733              
734             =over 4
735              
736             =item toksref
737              
738             Reference to hash returned by call to tokenize. See bayes_learn
739             documentation for additional information on the format.
740              
741             =item probsref
742              
743             Reference to hash of calculated probabilities for tokens found in
744             the database.
745              
746             {
747             'SHA1 Hash Value' => {
748             'prob' => 'calculated probability',
749             'spam_count' => 'Total number of spam msgs w/ token',
750             'ham_count' => 'Total number of ham msgs w/ token',
751             'atime' => 'Atime value for token in database'
752             }
753             }
754              
755             =item score
756              
757             Score calculated for this particular message.
758              
759             =item msgatime
760              
761             Calculated atime of the message just learned, note it may have been adjusted
762             if it was determined to be too far into the future.
763              
764             =item significant_tokens
765              
766             Array ref of the tokens found to be significant in determining the score for
767             this message.
768              
769             =back
770              
771             =item $plugin->plugin_report ( { options ... } )
772              
773             Called if the message is to be reported as spam. If the reporting system is
774             available, the variable C<$options-E<gt>{report}-E<gt>report_available}> should
775             be set to C<1>; if the reporting system successfully reported the message, the
776             variable C<$options-E<gt>{report}-E<gt>report_return}> should be set to C<1>.
777              
778             =over 4
779              
780             =item report
781              
782             Reference to the Reporter object (C<$options-E<gt>{report}> in the
783             paragraph above.)
784              
785             =item text
786              
787             Reference to a markup removed copy of the message in scalar string format.
788              
789             =item msg
790              
791             Reference to the original message object.
792              
793             =back
794              
795             =item $plugin->plugin_revoke ( { options ... } )
796              
797             Called if the message is to be reported as ham (revokes a spam report). If the
798             reporting system is available, the variable
799             C<$options-E<gt>{revoke}-E<gt>revoke_available}> should be set to C<1>; if the
800             reporting system successfully revoked the message, the variable
801             C<$options-E<gt>{revoke}-E<gt>revoke_return}> should be set to C<1>.
802              
803             =over 4
804              
805             =item revoke
806              
807             Reference to the Reporter object (C<$options-E<gt>{revoke}> in the
808             paragraph above.)
809              
810             =item text
811              
812             Reference to a markup removed copy of the message in scalar string format.
813              
814             =item msg
815              
816             Reference to the original message object.
817              
818             =back
819              
820             =item $plugin->whitelist_address( { options ... } )
821              
822             Called when a request is made to add an address to a
823             persistent address list.
824              
825             =over 4
826              
827             =item address
828              
829             Address you wish to add.
830              
831             =item cli_p
832              
833             Indicate if the call is being made from a command line interface.
834              
835             =back
836              
837             =item $plugin->blacklist_address( { options ... } )
838              
839             Called when a request is made to add an address to a
840             persistent address list.
841              
842             =over 4
843              
844             =item address
845              
846             Address you wish to add.
847              
848             =item cli_p
849              
850             Indicate if the call is being made from a command line interface.
851              
852             =back
853              
854             =item $plugin->remove_address( { options ... } )
855              
856             Called when a request is made to remove an address to a
857             persistent address list.
858              
859             =over 4
860              
861             =item address
862              
863             Address you wish to remove.
864              
865             =item cli_p
866              
867             Indicate if the call is being made from a command line interface.
868              
869             =back
870              
871             =item $plugin->spamd_child_init ()
872              
873             Called in each new child process when it starts up under spamd.
874              
875             =item $plugin->log_scan_result ( { options ... } )
876              
877             Called when spamd has completed scanning a message. Currently,
878             only spamd calls this API.
879              
880             =over 4
881              
882             =item result
883              
884             The C<'result: ...'> line for this scan. Format is as described
885             at B<http://wiki.apache.org/spamassassin/SpamdSyslogFormat>.
886              
887             =back
888              
889             =item $plugin->spamd_child_post_connection_close ()
890              
891             Called when child returns from handling a connection.
892              
893             If there was an accept failure, the child will die and this code will
894             not be called.
895              
896             =item $plugin->finish ()
897              
898             Called when the C<Mail::SpamAssassin> object is destroyed.
899              
900             =cut
901              
902             sub finish {
903 1079     1079 1 1363 my ($self) = @_;
904 1079         1149 %{$self} = ();
  1079         2349  
905             }
906              
907             =item $plugin->learner_new ()
908              
909             Used to support human-trained probabilistic classifiers like the BAYES_* ruleset.
910             Called when a new C<Mail::SpamAssassin::Bayes> object has been created; typically
911             when a new user's scan is about to start.
912              
913             =item $plugin->learn_message ()
914              
915             Train the classifier with a training message.
916              
917             =over 4
918              
919             =item isspam
920              
921             1 if the message is spam, 0 if it's non-spam.
922              
923             =item msg
924              
925             The message's C<Mail::SpamAssassin::Message> object.
926              
927             =item id
928              
929             An optional message-identification string, used internally to tag the message.
930             If it is C<undef>, one will be generated. It should be unique to that message.
931              
932             =back
933              
934             =item $plugin->forget_message ()
935              
936             Tell the classifier to 'forget' its training about a specific message.
937              
938             =over 4
939              
940             =item msg
941              
942             The message's C<Mail::SpamAssassin::Message> object.
943              
944             =item id
945              
946             An optional message-identification string, used internally to tag the message.
947             If it is C<undef>, one will be generated. It should be unique to that message.
948              
949             =back
950              
951             =item $plugin->learner_sync ()
952              
953             Tell the classifier to 'sync' any pending changes against the current
954             user's training database. This is called by C<sa-learn --sync>.
955              
956             If you do not need to implement these for your classifier, create an
957             implementation that just contains C<return 1>.
958              
959             =item $plugin->learner_expire_old_training ()
960              
961             Tell the classifier to perform infrequent, time-consuming cleanup of
962             the current user's training database. This is called by C<sa-learn
963             --force-expire>.
964              
965             If you do not need to implement these for your classifier, create an
966             implementation that just contains C<return 1>.
967              
968             =item $plugin->learner_is_scan_available ()
969              
970             Should return 1 if it is possible to use the current user's training data for
971             a message-scan operation, or 0 otherwise.
972              
973             =item $plugin->learner_dump_database ()
974              
975             Dump information about the current user's training data to C<stdout>.
976             This is called by C<sa-learn --dump>.
977              
978             =over 4
979              
980             =item magic
981              
982             Set to 1 if "magic" name-value metadata should be dumped.
983              
984             =item toks
985              
986             Set to 1 if the database of tokens should be dumped.
987              
988             =item regex
989              
990             Either C<undef> to dump all tokens, or a value which specifies a regular expression
991             subset of the tokens to dump.
992              
993             =back
994              
995             =item $plugin->learner_close ()
996              
997             Close any open databases.
998              
999             =over 4
1000              
1001             =item quiet
1002              
1003             Set to 1 if warning messages should be suppressed.
1004              
1005             =back
1006              
1007             =back
1008              
1009             =head1 HELPER APIS
1010              
1011             These methods provide an API for plugins to register themselves
1012             to receive specific events, or control the callback chain behaviour.
1013              
1014             =over 4
1015              
1016             =item $plugin->register_eval_rule ($nameofevalsub)
1017              
1018             Plugins that implement an eval test will need to call this, so that
1019             SpamAssassin calls into the object when that eval test is encountered.
1020             See the B<REGISTERING EVAL RULES> section for full details.
1021              
1022             =cut
1023              
1024             sub register_eval_rule {
1025 9449     9449 1 15009 my ($self, $nameofsub) = @_;
1026 9449         19393 $self->{main}->{conf}->register_eval_rule ($self, $nameofsub);
1027             }
1028              
1029             =item $plugin->register_generated_rule_method ($nameofsub)
1030              
1031             In certain circumstances, plugins may find it useful to compile
1032             perl functions from the ruleset, on the fly. It is important to
1033             remove these once the C<Mail::SpamAssassin> object is deleted,
1034             however, and this API allows this.
1035              
1036             Once the method C<$nameofsub> has been generated, call this API
1037             with the name of the method (including full package scope).
1038             This indicates that it's a temporary piece of generated code,
1039             built from the SpamAssassin ruleset, and when
1040             C<Mail::SpamAssassin::finish()> is called, the method will
1041             be destroyed.
1042              
1043             This API was added in SpamAssassin 3.2.0.
1044              
1045             =cut
1046              
1047             sub register_generated_rule_method {
1048 0     0 1   my ($self, $nameofsub) = @_;
1049 0           push @Mail::SpamAssassin::PerMsgStatus::TEMPORARY_METHODS,
1050             $nameofsub;
1051             }
1052              
1053             =item $plugin->register_method_priority($methodname, $priority)
1054              
1055             Indicate that the method named C<$methodname> on the current object
1056             has a callback priority of C<$priority>.
1057              
1058             This is used by the plugin handler to determine the relative order of
1059             callbacks; plugins with lower-numbered priorities are called before plugins
1060             with higher-numbered priorities. Each method can have a different priority
1061             value. The default value is C<0>. The ordering of callbacks to methods with
1062             equal priority is undefined.
1063              
1064             Typically, you only need to worry about this if you need to ensure your
1065             plugin's method is called before another plugin's implementation of that
1066             method. It should be called from your plugin's constructor.
1067              
1068             This API was added in SpamAssassin 3.2.0.
1069              
1070             =cut
1071              
1072             sub register_method_priority {
1073 0     0 1   my ($self, $methname, $pri) = @_;
1074 0           $self->{method_priority}->{$methname} = $pri;
1075             }
1076              
1077             =item $plugin->inhibit_further_callbacks()
1078              
1079             Tells the plugin handler to inhibit calling into other plugins in the plugin
1080             chain for the current callback. Frequently used when parsing configuration
1081             settings using C<parse_config()>.
1082              
1083             =back
1084              
1085             =cut
1086              
1087             sub inhibit_further_callbacks {
1088 0     0 1   my ($self) = @_;
1089 0           $self->{_inhibit_further_callbacks} = 1;
1090             }
1091              
1092             1;
1093             __END__
1094              
1095             =head1 LOGGING
1096              
1097             =over 4
1098              
1099             =item Mail::SpamAssassin::Plugin::dbg($message)
1100              
1101             Output a debugging message C<$message>, if the SpamAssassin object is running
1102             with debugging turned on.
1103              
1104             I<NOTE:> This function is not available in the package namespace
1105             of general plugins and can't be called via $self->dbg(). If a
1106             plugin wishes to output debug information, it should call
1107             C<Mail::SpamAssassin::Plugin::dbg($msg)>.
1108              
1109             =item Mail::SpamAssassin::Plugin::info($message)
1110              
1111             Output an informational message C<$message>, if the SpamAssassin object
1112             is running with informational messages turned on.
1113              
1114             I<NOTE:> This function is not available in the package namespace
1115             of general plugins and can't be called via $self->info(). If a
1116             plugin wishes to output debug information, it should call
1117             C<Mail::SpamAssassin::Plugin::info($msg)>.
1118              
1119             In general, it is better for plugins to use the C<Mail::SpamAssassin::Logger>
1120             module to import C<dbg> and C<info> directly, like so:
1121              
1122             use Mail::SpamAssassin::Logger;
1123             dbg("some message");
1124             info("some other message");
1125              
1126             =back
1127              
1128             =head1 REGISTERING EVAL RULES
1129              
1130             Plugins that implement an eval test must register the methods that can be
1131             called from rules in the configuration files, in the plugin class' constructor.
1132              
1133             For example,
1134              
1135             $plugin->register_eval_rule ('check_for_foo')
1136              
1137             will cause C<$plugin-E<gt>check_for_foo()> to be called for this
1138             SpamAssassin rule:
1139              
1140             header FOO_RULE eval:check_for_foo()
1141              
1142             Note that eval rules are passed the following arguments:
1143              
1144             =over 4
1145              
1146             =item - The plugin object itself
1147              
1148             =item - The C<Mail::SpamAssassin::PerMsgStatus> object calling the rule
1149              
1150             =item - standard arguments for the rule type in use
1151              
1152             =item - any and all arguments as specified in the configuration file
1153              
1154             =back
1155              
1156             In other words, the eval test method should look something like this:
1157              
1158             sub check_for_foo {
1159             my ($self, $permsgstatus, ...arguments...) = @_;
1160             ...code returning 0 or 1
1161             }
1162              
1163             Note that the headers can be accessed using the C<get()> method on the
1164             C<Mail::SpamAssassin::PerMsgStatus> object, and the body by
1165             C<get_decoded_stripped_body_text_array()> and other similar methods.
1166             Similarly, the C<Mail::SpamAssassin::Conf> object holding the current
1167             configuration may be accessed through C<$permsgstatus-E<gt>{main}-E<gt>{conf}>.
1168              
1169             The eval rule should return C<1> for a hit, or C<0> if the rule
1170             is not hit.
1171              
1172             State for a single message being scanned should be stored on the C<$permsgstatus>
1173             object, not on the C<$self> object, since C<$self> persists between scan
1174             operations. See the 'lifecycle note' on the C<check_start()> method above.
1175              
1176             =head1 STANDARD ARGUMENTS FOR RULE TYPES
1177              
1178             Plugins will be called with the same arguments as a standard EvalTest.
1179             Different rule types receive different information by default:
1180              
1181             =over 4
1182              
1183             =item - header tests: no extra arguments
1184              
1185             =item - body tests: fully rendered message as array reference
1186              
1187             =item - rawbody tests: fully decoded message as array reference
1188              
1189             =item - full tests: pristine message as scalar reference
1190              
1191             =back
1192              
1193             The configuration file arguments will be passed in after the standard
1194             arguments.
1195              
1196             =head1 BACKWARD COMPATIBILITY
1197              
1198             Note that if you write a plugin and need to determine if a particular
1199             helper method is supported on C<Mail::SpamAssassin::Plugin>, you
1200             can do this:
1201              
1202             if ($self->can("name_of_method")) {
1203             eval {
1204             $self->name_of_method(); # etc.
1205             }
1206             } else {
1207             # take fallback action
1208             }
1209              
1210             The same applies for the public APIs on objects of other types, such as
1211             C<Mail::SpamAssassin::PerMsgStatus>.
1212              
1213             =head1 SEE ALSO
1214              
1215             C<Mail::SpamAssassin>
1216              
1217             C<Mail::SpamAssassin::PerMsgStatus>
1218              
1219             http://wiki.apache.org/spamassassin/PluginWritingTips
1220              
1221             http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163
1222              
1223             =cut