You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by jm...@apache.org on 2007/07/25 14:52:48 UTC
svn commit: r559437 [7/13] - in /spamassassin/site/full/3.2.x: ./ doc/
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,579 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PerMsgStatus - per-message status</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $spamtest = new Mail::SpamAssassin ({
+ 'rules_filename' => '/etc/spamassassin.rules',
+ 'userprefs_filename' => $ENV{HOME}.'/.spamassassin/user_prefs'
+ });
+ my $mail = $spamtest->parse();</pre>
+<pre>
+ my $status = $spamtest->check ($mail);</pre>
+<pre>
+ my $rewritten_mail;
+ if ($status->is_spam()) {
+ $rewritten_mail = $status->rewrite_mail ();
+ }
+ ...</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The Mail::SpamAssassin <a href="#item_check"><code>check()</code></a> method returns an object of this
+class. This object encapsulates all the per-message state.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_check">$status->check ()</a></strong><br />
+</dt>
+<dd>
+Runs the SpamAssassin rules against the message pointed to by the object.
+</dd>
+<p></p>
+<dt><strong><a name="item_learn">$status-><code>learn()</code></a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. If the score
+is outside a certain range around the threshold, ie. if the message is judged
+more-or-less definitely spam or definitely non-spam, it will be fed into
+SpamAssassin's learning systems (currently the naive Bayesian classifier),
+so that future similar mails will be caught.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_autolearn_points">$score = $status-><code>get_autolearn_points()</code></a></strong><br />
+</dt>
+<dd>
+Return the message's score as computed for auto-learning. Certain tests are
+ignored:
+</dd>
+<dd>
+<pre>
+ - rules with tflags set to 'learn' (the Bayesian rules)</pre>
+</dd>
+<dd>
+<pre>
+ - rules with tflags set to 'userconf' (user white/black-listing rules, etc)</pre>
+</dd>
+<dd>
+<pre>
+ - rules with tflags set to 'noautolearn'</pre>
+</dd>
+<dd>
+<p>Also note that auto-learning occurs using scores from either scoreset 0 or 1,
+depending on what scoreset is used during message check. It is likely that the
+message check and auto-learn scores will be different.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_head_only_points">$score = $status-><code>get_head_only_points()</code></a></strong><br />
+</dt>
+<dd>
+Return the message's score as computed for auto-learning, ignoring
+all rules except for header-based ones.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_learned_points">$score = $status-><code>get_learned_points()</code></a></strong><br />
+</dt>
+<dd>
+Return the message's score as computed for auto-learning, ignoring
+all rules except for learning-based ones.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_body_only_points">$score = $status-><code>get_body_only_points()</code></a></strong><br />
+</dt>
+<dd>
+Return the message's score as computed for auto-learning, ignoring
+all rules except for body-based ones.
+</dd>
+<p></p>
+<dt><strong><a name="item_is_spam">$isspam = $status->is_spam ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return 1 for mail determined likely to be spam, 0 if it does not seem
+spam-like.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_names_of_tests_hit">$list = $status->get_names_of_tests_hit ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return a comma-separated string, listing all the symbolic test names
+of the tests which were trigged by the mail.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_names_of_subtests_hit">$list = $status->get_names_of_subtests_hit ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return a comma-separated string, listing all the symbolic test names of the
+meta-rule sub-tests which were trigged by the mail. Sub-tests are the
+normally-hidden rules, which score 0 and have names beginning with two
+underscores, used in meta rules.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_score">$num = $status->get_score ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return the message's score.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_required_score">$num = $status->get_required_score ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return the score required for a mail to be considered spam.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_autolearn_status">$num = $status->get_autolearn_status ()</a></strong><br />
+</dt>
+<dd>
+After a mail message has been checked, this method can be called. It will
+return one of the following strings depending on whether the mail was
+auto-learned or not: ``ham'', ``no'', ``spam'', ``disabled'', ``failed'', ``unavailable''.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_report">$report = $status->get_report ()</a></strong><br />
+</dt>
+<dd>
+Deliver a ``spam report'' on the checked mail message. This contains details of
+how many spam detection rules it triggered.
+</dd>
+<dd>
+<p>The report is returned as a multi-line string, with the lines separated by
+<code>\n</code> characters.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_content_preview">$preview = $status->get_content_preview ()</a></strong><br />
+</dt>
+<dd>
+Give a ``preview'' of the content.
+</dd>
+<dd>
+<p>This is returned as a multi-line string, with the lines separated by <code>\n</code>
+characters, containing a fully-decoded, safe, plain-text sample of the first
+few lines of the message body.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_message">$msg = $status-><code>get_message()</code></a></strong><br />
+</dt>
+<dd>
+Return the object representing the message being scanned.
+</dd>
+<p></p>
+<dt><strong><a name="item_rewrite_mail">$status->rewrite_mail ()</a></strong><br />
+</dt>
+<dd>
+Rewrite the mail message. This will at minimum add headers, and at
+maximum MIME-encapsulate the message text, to reflect its spam or not-spam
+status. The function will return a scalar of the rewritten message.
+</dd>
+<dd>
+<p>The actual modifications depend on the configuration (see
+<code>Mail::SpamAssassin::Conf</code> for more information).</p>
+</dd>
+<dd>
+<p>The possible modifications are as follows:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_to_3a_2c_from_3a_and_subject_3a_modification_on_sp">To:, From: and Subject: modification on spam mails</a></strong><br />
+</dt>
+<dd>
+Depending on the configuration, the To: and From: lines can have a
+user-defined RFC 2822 comment appended for spam mail. The subject line
+may have a user-defined string prepended to it for spam mail.
+</dd>
+<p></p>
+<dt><strong><a name="item_x_2dspam_2d_2a_headers_for_all_mails">X-Spam-* headers for all mails</a></strong><br />
+</dt>
+<dd>
+Depending on the configuration, zero or more headers with names
+beginning with <code>X-Spam-</code> will be added to mail depending on whether
+it is spam or ham.
+</dd>
+<p></p>
+<dt><strong><a name="item_spam_message_with_report_safe">spam message with report_safe</a></strong><br />
+</dt>
+<dd>
+If report_safe is set to true (1), then spam messages are encapsulated
+into their own message/rfc822 MIME attachment without any modifications
+being made.
+</dd>
+<dd>
+<p>If report_safe is set to false (0), then the message will only have the
+above headers added/modified.</p>
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_set_tag">$status->set_tag($tagname, $value)</a></strong><br />
+</dt>
+<dd>
+Set a template tag, as used in <code>add_header</code>, report templates, etc. This API
+is intended for use by plugins. Tag names will be converted to an
+all-uppercase representation internally.
+</dd>
+<dd>
+<p><code>$value</code> can be a subroutine reference, which will be evaluated each time
+the template is expanded. Note that perl supports closures, which means
+that variables set in the caller's scope can be accessed inside this <code>sub</code>.
+For example:</p>
+</dd>
+<dd>
+<pre>
+ my $text = "hello world!";
+ $status->set_tag("FOO", sub {
+ return $text;
+ });</pre>
+</dd>
+<dd>
+<p>See <code>Mail::SpamAssassin::Conf</code>'s <code>TEMPLATE TAGS</code> section for more details on
+how template tags are used.</p>
+</dd>
+<dd>
+<p><code>undef</code> will be returned if a tag by that name has not been defined.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_tag">$string = $status-><code>get_tag($tagname)</code></a></strong><br />
+</dt>
+<dd>
+Get the current value of a template tag, as used in <code>add_header</code>, report
+templates, etc. This API is intended for use by plugins. Tag names will be
+converted to an all-uppercase representation internally. See
+<code>Mail::SpamAssassin::Conf</code>'s <code>TEMPLATE TAGS</code> section for more details on
+tags.
+</dd>
+<dd>
+<p><code>undef</code> will be returned if a tag by that name has not been defined.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_set_spamd_result_item">$status-><code>set_spamd_result_item($subref)</code></a></strong><br />
+</dt>
+<dd>
+Set an entry for the spamd result log line. <code>$subref</code> should be a code
+reference for a subroutine which will return a string in <code>'name=VALUE'</code>
+format, similar to the other entries in the spamd result line:
+</dd>
+<dd>
+<pre>
+ Jul 17 14:10:47 radish spamd[16670]: spamd: result: Y 22 - ALL_NATURAL,
+ DATE_IN_FUTURE_03_06,DIET_1,DRUGS_ERECTILE,DRUGS_PAIN,
+ TEST_FORGED_YAHOO_RCVD,TEST_INVALID_DATE,TEST_NOREALNAME,
+ TEST_NORMAL_HTTP_TO_IP,UNDISC_RECIPS scantime=0.4,size=3138,user=jm,
+ uid=1000,required_score=5.0,rhost=localhost,raddr=127.0.0.1,
+ rport=33153,mid=<9PS291LhupY>,autolearn=spam</pre>
+</dd>
+<dd>
+<p><code>name</code> and <code>VALUE</code> must not contain <code>=</code> or <code>,</code> characters, as it
+is important that these log lines are easy to parse.</p>
+</dd>
+<dd>
+<p>The code reference will be called by spamd after the message has been scanned,
+and the <a href="#item_check"><code>PerMsgStatus::check()</code></a> method has returned.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$status->finish ()</a></strong><br />
+</dt>
+<dd>
+Indicate that this <code>$status</code> object is finished with, and can be destroyed.
+</dd>
+<dd>
+<p>If you are using SpamAssassin in a persistent environment, or checking many
+mail messages from one <code>Mail::SpamAssassin</code> factory, this method should be
+called to ensure Perl's garbage collection will clean up old status objects.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_current_eval_rule_name">$name = $status-><code>get_current_eval_rule_name()</code></a></strong><br />
+</dt>
+<dd>
+Return the name of the currently-running eval rule. <code>undef</code> is
+returned if no eval rule is currently being run. Useful for plugins
+to determine the current rule name while inside an eval test function
+call.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_decoded_body_text_array">$status->get_decoded_body_text_array ()</a></strong><br />
+</dt>
+<dd>
+Returns the message body, with <strong>base64</strong> or <strong>quoted-printable</strong> encodings
+decoded, and non-text parts or non-inline attachments stripped.
+</dd>
+<dd>
+<p>It is returned as an array of strings, with each string representing
+one newline-separated line of the body.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_decoded_stripped_body_text_array">$status->get_decoded_stripped_body_text_array ()</a></strong><br />
+</dt>
+<dd>
+Returns the message body, decoded (as described in
+get_decoded_body_text_array()), with HTML rendered, and with whitespace
+normalized.
+</dd>
+<dd>
+<p>It will always render text/html, and will use a heuristic to determine if other
+text/* parts should be considered text/html.</p>
+</dd>
+<dd>
+<p>It is returned as an array of strings, with each string representing one
+'paragraph'. Paragraphs, in plain-text mails, are double-newline-separated
+blocks of multi-line text.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get">$status->get (header_name [, default_value])</a></strong><br />
+</dt>
+<dd>
+Returns a message header, pseudo-header, real name or address.
+<code>header_name</code> is the name of a mail header, such as 'Subject', 'To',
+etc. If <code>default_value</code> is given, it will be used if the requested
+<code>header_name</code> does not exist.
+</dd>
+<dd>
+<p>Appending <code>:raw</code> to the header name will inhibit decoding of quoted-printable
+or base-64 encoded strings.</p>
+</dd>
+<dd>
+<p>Appending <code>:addr</code> to the header name will cause everything except
+the first email address to be removed from the header. For example,
+all of the following will result in ``example@foo'':</p>
+</dd>
+<dl>
+<dt><strong><a name="item_example_40foo">example@foo</a></strong><br />
+</dt>
+<dt><strong><a name="item_foo">example@foo (Foo Blah)</a></strong><br />
+</dt>
+<dt><strong><a name="item_example_40foo_2c_example_40bar">example@foo, example@bar</a></strong><br />
+</dt>
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong><br />
+</dt>
+<dt><strong><a name="item_foo_blah__3cexample_40foo_3e">Foo Blah <example@foo></a></strong><br />
+</dt>
+<dt><strong><a name="item__22foo_blah_22__3cexample_40foo_3e">``Foo Blah'' <example@foo></a></strong><br />
+</dt>
+<dt><strong><a name="item__22_27foo_blah_27_22__3cexample_40foo_3e">``'Foo Blah''' <example@foo></a></strong><br />
+</dt>
+</dl>
+<p>Appending <code>:name</code> to the header name will cause everything except
+the first real name to be removed from the header. For example,
+all of the following will result in ``Foo Blah''</p>
+<dl>
+<dt><strong>example@foo (Foo Blah)</strong><br />
+</dt>
+<dt><strong>example@foo (Foo Blah), example@bar</strong><br />
+</dt>
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong><br />
+</dt>
+<dt><strong>Foo Blah <example@foo></strong><br />
+</dt>
+<dt><strong>``Foo Blah'' <example@foo></strong><br />
+</dt>
+<dt><strong>``'Foo Blah''' <example@foo></strong><br />
+</dt>
+</dl>
+<p>There are several special pseudo-headers that can be specified:</p>
+<dl>
+<dt><strong><a name="item_all_can_be_used_to_mean_the_text_of_all_the_messag"><code>ALL</code> can be used to mean the text of all the message's headers.</a></strong><br />
+</dt>
+<dt><strong><a name="item_all_2dtrusted_can_be_used_to_mean_the_text_of_all_"><code>ALL-TRUSTED</code> can be used to mean the text of all the message's headers
+that could only have been added by trusted relays.</a></strong><br />
+</dt>
+<dt><strong><a name="item_all_2dinternal_can_be_used_to_mean_the_text_of_all"><code>ALL-INTERNAL</code> can be used to mean the text of all the message's headers
+that could only have been added by internal relays.</a></strong><br />
+</dt>
+<dt><strong><a name="item_all_2duntrusted_can_be_used_to_mean_the_text_of_al"><code>ALL-UNTRUSTED</code> can be used to mean the text of all the message's
+headers that may have been added by untrusted relays. To make this
+pseudo-header more useful for header rules the 'Received' header that was added
+by the last trusted relay is included, even though it can be trusted.</a></strong><br />
+</dt>
+<dt><strong><a name="item_all_2dexternal_can_be_used_to_mean_the_text_of_all"><code>ALL-EXTERNAL</code> can be used to mean the text of all the message's headers
+that may have been added by external relays. Like <code>ALL-UNTRUSTED</code> the
+'Received' header added by the last internal relay is included.</a></strong><br />
+</dt>
+<dt><strong><a name="item_tocc_can_be_used_to_mean_the_contents_of_both_the_"><code>ToCc</code> can be used to mean the contents of both the 'To' and 'Cc'
+headers.</a></strong><br />
+</dt>
+<dt><strong><a name="item_envelopefrom_is_the_address_used_in_the__27mail_fr"><code>EnvelopeFrom</code> is the address used in the 'MAIL FROM:' phase of the SMTP
+transaction that delivered this message, if this data has been made available
+by the SMTP server.</a></strong><br />
+</dt>
+<dt><strong><a name="item_messageid_is_a_symbol_meaning_all_message_2did_27s"><code>MESSAGEID</code> is a symbol meaning all Message-Id's found in the message;
+some mailing list software moves the real 'Message-Id' to 'Resent-Message-Id'
+or 'X-Message-Id', then uses its own one in the 'Message-Id' header. The value
+returned for this symbol is the text from all 3 headers, separated by newlines.</a></strong><br />
+</dt>
+<dt><strong><a name="item_x_2dspam_2drelays_2duntrusted_is_the_generated_met"><code>X-Spam-Relays-Untrusted</code> is the generated metadata of untrusted relays
+the message has passed through</a></strong><br />
+</dt>
+<dt><strong><a name="item_x_2dspam_2drelays_2dtrusted_is_the_generated_metad"><code>X-Spam-Relays-Trusted</code> is the generated metadata of trusted relays
+the message has passed through</a></strong><br />
+</dt>
+</dl>
+<dt><strong><a name="item_get_uri_list">$status->get_uri_list ()</a></strong><br />
+</dt>
+<dd>
+Returns an array of all unique URIs found in the message. It takes
+a combination of the URIs found in the rendered (decoded and HTML
+stripped) body and the URIs found when parsing the HTML in the message.
+Will also set $status->{uri_list} (the array as returned by this function).
+</dd>
+<dd>
+<p>The returned array will include the ``raw'' URI as well as
+``slightly cooked'' versions. For example, the single URI
+'http://%77&#00119;%77.example.com/' will get turned into:
+( 'http://%77&#00119;%77.example.com/', 'http://www.example.com/' )</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_uri_detail_list">$status->get_uri_detail_list ()</a></strong><br />
+</dt>
+<dd>
+Returns a hash reference of all unique URIs found in the message and
+various data about where the URIs were found in the message. It takes a
+combination of the URIs found in the rendered (decoded and HTML stripped)
+body and the URIs found when parsing the HTML in the message. Will also
+set $status->{uri_detail_list} (the hash reference as returned by this
+function). This function will also set $status->{uri_domain_count} (count of
+unique domains).
+</dd>
+<dd>
+<p>The hash format looks something like this:</p>
+</dd>
+<dd>
+<pre>
+ raw_uri => {
+ types => { a => 1, img => 1, parsed => 1 },
+ cleaned => [ canonified_uri ],
+ anchor_text => [ "click here", "no click here" ],
+ domains => { domain1 => 1, domain2 => 1 },
+ }</pre>
+</dd>
+<dd>
+<p><code>raw_uri</code> is whatever the URI was in the message itself
+(http://spamassassin.apache%2Eorg/).</p>
+</dd>
+<dd>
+<p><code>types</code> is a hash of the HTML tags (lowercase) which referenced
+the raw_uri. <em>parsed</em> is a faked type which specifies that the
+raw_uri was seen in the rendered text.</p>
+</dd>
+<dd>
+<p><code>cleaned</code> is an array of the raw and canonified version of the raw_uri
+(http://spamassassin.apache%2Eorg/, <a href="http://spamassassin.apache.org/).">http://spamassassin.apache.org/).</a></p>
+</dd>
+<dd>
+<p><code>anchor_text</code> is an array of the anchor text (text between <a> and
+</a>), if any, which linked to the URI.</p>
+</dd>
+<dd>
+<p><code>domains</code> is a hash of the domains found in the canonified URIs.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_test_state">$status-><code>clear_test_state()</code></a></strong><br />
+</dt>
+<dd>
+Clear test state, including test log messages from <code>$status->test_log()</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_got_hit">$status->got_hit ($rulename, $desc_prepend [, name => value, ...])</a></strong><br />
+</dt>
+<dd>
+Register a hit against a rule in the ruleset.
+</dd>
+<dd>
+<p>There are two mandatory arguments. These are <code>$rulename</code>, the name of the rule
+that fired, and <code>$desc_prepend</code>, which is a short string that will be
+prepended to the rules <code>describe</code> string in output reports.</p>
+</dd>
+<dd>
+<p>In addition, callers can supplement that with the following optional
+data:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_score__3d_3e__24num">score => $num</a></strong><br />
+</dt>
+<dd>
+Optional: the score to use for the rule hit. If unspecified,
+the value from the <code>Mail::SpamAssassin::Conf</code> object's <code>{scores}</code>
+hash will be used.
+</dd>
+<p></p>
+<dt><strong><a name="item_value__3d_3e__24num">value => $num</a></strong><br />
+</dt>
+<dd>
+Optional: the value to assign to the rule; the default value is <code>1</code>.
+<em>tflags multiple</em> rules use values of greater than 1 to indicate
+multiple hits. This value is accessible to meta rules.
+</dd>
+<p></p>
+<dt><strong><a name="item_ruletype__3d_3e__24type">ruletype => $type</a></strong><br />
+</dt>
+<dd>
+Optional, but recommended: the rule type string. This is used in the
+<code>hit_rule</code> plugin call, called by this method. If unset, <em>'unknown'</em> is
+used.
+</dd>
+<p></p></dl>
+<p>Backwards compatibility: the two mandatory arguments have been part of this API
+since SpamAssassin 2.x. The optional <em>name=<gt</em>value> pairs, however, are a
+new addition in SpamAssassin 3.2.0.</p>
+<dt><strong><a name="item_create_fulltext_tmpfile">$status->create_fulltext_tmpfile (fulltext_ref)</a></strong><br />
+</dt>
+<dd>
+This function creates a temporary file containing the passed scalar
+reference data (typically the full/pristine text of the message).
+This is typically used by external programs like pyzor and dccproc, to
+avoid hangs due to buffering issues. Methods that need this, should
+call $self-><a href="#item_create_fulltext_tmpfile"><code>create_fulltext_tmpfile($fulltext)</code></a> to retrieve the temporary
+filename; it will be created if it has not already been.
+</dd>
+<dd>
+<p>Note: This can only be called once until $status-><a href="#item_delete_fulltext_tmpfile"><code>delete_fulltext_tmpfile()</code></a> is
+called.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_delete_fulltext_tmpfile">$status->delete_fulltext_tmpfile ()</a></strong><br />
+</dt>
+<dd>
+Will cleanup after a $status-><a href="#item_create_fulltext_tmpfile"><code>create_fulltext_tmpfile()</code></a> call. Deletes the
+temporary file and uncaches the filename.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::SpamAssassin</code>
+<code>spamassassin</code>
+
+</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.txt?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.txt Wed Jul 25 05:52:42 2007
@@ -0,0 +1,383 @@
+NAME
+ Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)
+
+SYNOPSIS
+ my $spamtest = new Mail::SpamAssassin ({
+ 'rules_filename' => '/etc/spamassassin.rules',
+ 'userprefs_filename' => $ENV{HOME}.'/.spamassassin/user_prefs'
+ });
+ my $mail = $spamtest->parse();
+
+ my $status = $spamtest->check ($mail);
+
+ my $rewritten_mail;
+ if ($status->is_spam()) {
+ $rewritten_mail = $status->rewrite_mail ();
+ }
+ ...
+
+DESCRIPTION
+ The Mail::SpamAssassin "check()" method returns an object of this class.
+ This object encapsulates all the per-message state.
+
+METHODS
+ $status->check ()
+ Runs the SpamAssassin rules against the message pointed to by the
+ object.
+
+ $status->learn()
+ After a mail message has been checked, this method can be called. If
+ the score is outside a certain range around the threshold, ie. if
+ the message is judged more-or-less definitely spam or definitely
+ non-spam, it will be fed into SpamAssassin's learning systems
+ (currently the naive Bayesian classifier), so that future similar
+ mails will be caught.
+
+ $score = $status->get_autolearn_points()
+ Return the message's score as computed for auto-learning. Certain
+ tests are ignored:
+
+ - rules with tflags set to 'learn' (the Bayesian rules)
+
+ - rules with tflags set to 'userconf' (user white/black-listing rules, etc)
+
+ - rules with tflags set to 'noautolearn'
+
+ Also note that auto-learning occurs using scores from either
+ scoreset 0 or 1, depending on what scoreset is used during message
+ check. It is likely that the message check and auto-learn scores
+ will be different.
+
+ $score = $status->get_head_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for header-based ones.
+
+ $score = $status->get_learned_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for learning-based ones.
+
+ $score = $status->get_body_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for body-based ones.
+
+ $isspam = $status->is_spam ()
+ After a mail message has been checked, this method can be called. It
+ will return 1 for mail determined likely to be spam, 0 if it does
+ not seem spam-like.
+
+ $list = $status->get_names_of_tests_hit ()
+ After a mail message has been checked, this method can be called. It
+ will return a comma-separated string, listing all the symbolic test
+ names of the tests which were trigged by the mail.
+
+ $list = $status->get_names_of_subtests_hit ()
+ After a mail message has been checked, this method can be called. It
+ will return a comma-separated string, listing all the symbolic test
+ names of the meta-rule sub-tests which were trigged by the mail.
+ Sub-tests are the normally-hidden rules, which score 0 and have
+ names beginning with two underscores, used in meta rules.
+
+ $num = $status->get_score ()
+ After a mail message has been checked, this method can be called. It
+ will return the message's score.
+
+ $num = $status->get_required_score ()
+ After a mail message has been checked, this method can be called. It
+ will return the score required for a mail to be considered spam.
+
+ $num = $status->get_autolearn_status ()
+ After a mail message has been checked, this method can be called. It
+ will return one of the following strings depending on whether the
+ mail was auto-learned or not: "ham", "no", "spam", "disabled",
+ "failed", "unavailable".
+
+ $report = $status->get_report ()
+ Deliver a "spam report" on the checked mail message. This contains
+ details of how many spam detection rules it triggered.
+
+ The report is returned as a multi-line string, with the lines
+ separated by "\n" characters.
+
+ $preview = $status->get_content_preview ()
+ Give a "preview" of the content.
+
+ This is returned as a multi-line string, with the lines separated by
+ "\n" characters, containing a fully-decoded, safe, plain-text sample
+ of the first few lines of the message body.
+
+ $msg = $status->get_message()
+ Return the object representing the message being scanned.
+
+ $status->rewrite_mail ()
+ Rewrite the mail message. This will at minimum add headers, and at
+ maximum MIME-encapsulate the message text, to reflect its spam or
+ not-spam status. The function will return a scalar of the rewritten
+ message.
+
+ The actual modifications depend on the configuration (see
+ "Mail::SpamAssassin::Conf" for more information).
+
+ The possible modifications are as follows:
+
+ To:, From: and Subject: modification on spam mails
+ Depending on the configuration, the To: and From: lines can have
+ a user-defined RFC 2822 comment appended for spam mail. The
+ subject line may have a user-defined string prepended to it for
+ spam mail.
+
+ X-Spam-* headers for all mails
+ Depending on the configuration, zero or more headers with names
+ beginning with "X-Spam-" will be added to mail depending on
+ whether it is spam or ham.
+
+ spam message with report_safe
+ If report_safe is set to true (1), then spam messages are
+ encapsulated into their own message/rfc822 MIME attachment
+ without any modifications being made.
+
+ If report_safe is set to false (0), then the message will only
+ have the above headers added/modified.
+
+ $status->set_tag($tagname, $value)
+ Set a template tag, as used in "add_header", report templates, etc.
+ This API is intended for use by plugins. Tag names will be converted
+ to an all-uppercase representation internally.
+
+ $value can be a subroutine reference, which will be evaluated each
+ time the template is expanded. Note that perl supports closures,
+ which means that variables set in the caller's scope can be accessed
+ inside this "sub". For example:
+
+ my $text = "hello world!";
+ $status->set_tag("FOO", sub {
+ return $text;
+ });
+
+ See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" section for more
+ details on how template tags are used.
+
+ "undef" will be returned if a tag by that name has not been defined.
+
+ $string = $status->get_tag($tagname)
+ Get the current value of a template tag, as used in "add_header",
+ report templates, etc. This API is intended for use by plugins. Tag
+ names will be converted to an all-uppercase representation
+ internally. See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" section
+ for more details on tags.
+
+ "undef" will be returned if a tag by that name has not been defined.
+
+ $status->set_spamd_result_item($subref)
+ Set an entry for the spamd result log line. $subref should be a code
+ reference for a subroutine which will return a string in
+ 'name=VALUE' format, similar to the other entries in the spamd
+ result line:
+
+ Jul 17 14:10:47 radish spamd[16670]: spamd: result: Y 22 - ALL_NATURAL,
+ DATE_IN_FUTURE_03_06,DIET_1,DRUGS_ERECTILE,DRUGS_PAIN,
+ TEST_FORGED_YAHOO_RCVD,TEST_INVALID_DATE,TEST_NOREALNAME,
+ TEST_NORMAL_HTTP_TO_IP,UNDISC_RECIPS scantime=0.4,size=3138,user=jm,
+ uid=1000,required_score=5.0,rhost=localhost,raddr=127.0.0.1,
+ rport=33153,mid=<9PS291LhupY>,autolearn=spam
+
+ "name" and "VALUE" must not contain "=" or "," characters, as it is
+ important that these log lines are easy to parse.
+
+ The code reference will be called by spamd after the message has
+ been scanned, and the "PerMsgStatus::check()" method has returned.
+
+ $status->finish ()
+ Indicate that this $status object is finished with, and can be
+ destroyed.
+
+ If you are using SpamAssassin in a persistent environment, or
+ checking many mail messages from one "Mail::SpamAssassin" factory,
+ this method should be called to ensure Perl's garbage collection
+ will clean up old status objects.
+
+ $name = $status->get_current_eval_rule_name()
+ Return the name of the currently-running eval rule. "undef" is
+ returned if no eval rule is currently being run. Useful for plugins
+ to determine the current rule name while inside an eval test
+ function call.
+
+ $status->get_decoded_body_text_array ()
+ Returns the message body, with base64 or quoted-printable encodings
+ decoded, and non-text parts or non-inline attachments stripped.
+
+ It is returned as an array of strings, with each string representing
+ one newline-separated line of the body.
+
+ $status->get_decoded_stripped_body_text_array ()
+ Returns the message body, decoded (as described in
+ get_decoded_body_text_array()), with HTML rendered, and with
+ whitespace normalized.
+
+ It will always render text/html, and will use a heuristic to
+ determine if other text/* parts should be considered text/html.
+
+ It is returned as an array of strings, with each string representing
+ one 'paragraph'. Paragraphs, in plain-text mails, are
+ double-newline-separated blocks of multi-line text.
+
+ $status->get (header_name [, default_value])
+ Returns a message header, pseudo-header, real name or address.
+ "header_name" is the name of a mail header, such as 'Subject', 'To',
+ etc. If "default_value" is given, it will be used if the requested
+ "header_name" does not exist.
+
+ Appending ":raw" to the header name will inhibit decoding of
+ quoted-printable or base-64 encoded strings.
+
+ Appending ":addr" to the header name will cause everything except
+ the first email address to be removed from the header. For example,
+ all of the following will result in "example@foo":
+
+ example@foo
+ example@foo (Foo Blah)
+ example@foo, example@bar
+ display: example@foo (Foo Blah), example@bar ;
+ Foo Blah <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@foo>
+
+ Appending ":name" to the header name will cause everything except
+ the first real name to be removed from the header. For example, all
+ of the following will result in "Foo Blah"
+
+ example@foo (Foo Blah)
+ example@foo (Foo Blah), example@bar
+ display: example@foo (Foo Blah), example@bar ;
+ Foo Blah <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@foo>
+
+ There are several special pseudo-headers that can be specified:
+
+ "ALL" can be used to mean the text of all the message's headers.
+ "ALL-TRUSTED" can be used to mean the text of all the message's
+ headers that could only have been added by trusted relays.
+ "ALL-INTERNAL" can be used to mean the text of all the message's
+ headers that could only have been added by internal relays.
+ "ALL-UNTRUSTED" can be used to mean the text of all the message's
+ headers that may have been added by untrusted relays. To make this
+ pseudo-header more useful for header rules the 'Received' header
+ that was added by the last trusted relay is included, even though it
+ can be trusted.
+ "ALL-EXTERNAL" can be used to mean the text of all the message's
+ headers that may have been added by external relays. Like
+ "ALL-UNTRUSTED" the 'Received' header added by the last internal
+ relay is included.
+ "ToCc" can be used to mean the contents of both the 'To' and 'Cc'
+ headers.
+ "EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the
+ SMTP transaction that delivered this message, if this data has been
+ made available by the SMTP server.
+ "MESSAGEID" is a symbol meaning all Message-Id's found in the
+ message; some mailing list software moves the real 'Message-Id' to
+ 'Resent-Message-Id' or 'X-Message-Id', then uses its own one in the
+ 'Message-Id' header. The value returned for this symbol is the text
+ from all 3 headers, separated by newlines.
+ "X-Spam-Relays-Untrusted" is the generated metadata of untrusted
+ relays the message has passed through
+ "X-Spam-Relays-Trusted" is the generated metadata of trusted relays
+ the message has passed through
+
+ $status->get_uri_list ()
+ Returns an array of all unique URIs found in the message. It takes a
+ combination of the URIs found in the rendered (decoded and HTML
+ stripped) body and the URIs found when parsing the HTML in the
+ message. Will also set $status->{uri_list} (the array as returned by
+ this function).
+
+ The returned array will include the "raw" URI as well as "slightly
+ cooked" versions. For example, the single URI
+ 'http://%77w%77.example.com/' will get turned into: (
+ 'http://%77w%77.example.com/', 'http://www.example.com/' )
+
+ $status->get_uri_detail_list ()
+ Returns a hash reference of all unique URIs found in the message and
+ various data about where the URIs were found in the message. It
+ takes a combination of the URIs found in the rendered (decoded and
+ HTML stripped) body and the URIs found when parsing the HTML in the
+ message. Will also set $status->{uri_detail_list} (the hash
+ reference as returned by this function). This function will also set
+ $status->{uri_domain_count} (count of unique domains).
+
+ The hash format looks something like this:
+
+ raw_uri => {
+ types => { a => 1, img => 1, parsed => 1 },
+ cleaned => [ canonified_uri ],
+ anchor_text => [ "click here", "no click here" ],
+ domains => { domain1 => 1, domain2 => 1 },
+ }
+
+ "raw_uri" is whatever the URI was in the message itself
+ (http://spamassassin.apache%2Eorg/).
+
+ "types" is a hash of the HTML tags (lowercase) which referenced the
+ raw_uri. *parsed* is a faked type which specifies that the raw_uri
+ was seen in the rendered text.
+
+ "cleaned" is an array of the raw and canonified version of the
+ raw_uri (http://spamassassin.apache%2Eorg/,
+ http://spamassassin.apache.org/).
+
+ "anchor_text" is an array of the anchor text (text between <a> and
+ </a>), if any, which linked to the URI.
+
+ "domains" is a hash of the domains found in the canonified URIs.
+
+ $status->clear_test_state()
+ Clear test state, including test log messages from
+ "$status->test_log()".
+
+ $status->got_hit ($rulename, $desc_prepend [, name => value, ...])
+ Register a hit against a rule in the ruleset.
+
+ There are two mandatory arguments. These are $rulename, the name of
+ the rule that fired, and $desc_prepend, which is a short string that
+ will be prepended to the rules "describe" string in output reports.
+
+ In addition, callers can supplement that with the following optional
+ data:
+
+ score => $num
+ Optional: the score to use for the rule hit. If unspecified, the
+ value from the "Mail::SpamAssassin::Conf" object's "{scores}"
+ hash will be used.
+
+ value => $num
+ Optional: the value to assign to the rule; the default value is
+ 1. *tflags multiple* rules use values of greater than 1 to
+ indicate multiple hits. This value is accessible to meta rules.
+
+ ruletype => $type
+ Optional, but recommended: the rule type string. This is used in
+ the "hit_rule" plugin call, called by this method. If unset,
+ *'unknown'* is used.
+
+ Backwards compatibility: the two mandatory arguments have been part
+ of this API since SpamAssassin 2.x. The optional *name=<gt*value>
+ pairs, however, are a new addition in SpamAssassin 3.2.0.
+
+ $status->create_fulltext_tmpfile (fulltext_ref)
+ This function creates a temporary file containing the passed scalar
+ reference data (typically the full/pristine text of the message).
+ This is typically used by external programs like pyzor and dccproc,
+ to avoid hangs due to buffering issues. Methods that need this,
+ should call $self->create_fulltext_tmpfile($fulltext) to retrieve
+ the temporary filename; it will be created if it has not already
+ been.
+
+ Note: This can only be called once until
+ $status->delete_fulltext_tmpfile() is called.
+
+ $status->delete_fulltext_tmpfile ()
+ Will cleanup after a $status->create_fulltext_tmpfile() call.
+ Deletes the temporary file and uncaches the filename.
+
+SEE ALSO
+ "Mail::SpamAssassin" "spamassassin"
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,112 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...</pre>
+<p>SpamAssassin will call:</p>
+<pre>
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>All persistent address list implementations, used by the auto-whitelist
+code to track known-good email addresses, use this as a base class.</p>
+<p>See <code>Mail::SpamAssassin::DBBasedAddrList</code> for an example.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_new">$factory = PersistentAddrListSubclass->new();</a></strong><br />
+</dt>
+<dd>
+This creates a factory object, which SpamAssassin will call to create
+a new checker object for the persistent address list.
+</dd>
+<p></p>
+<dt><strong><a name="item_new_checker">my $addrlist = $factory->new_checker();</a></strong><br />
+</dt>
+<dd>
+Create a new address-list checker object from the factory. Called by the
+SpamAssassin classes.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_addr_entry">$entry = $addrlist->get_addr_entry ($addr);</a></strong><br />
+</dt>
+<dd>
+Given an email address <code>$addr</code>, return an entry object with the details of
+that address.
+</dd>
+<dd>
+<p>The entry object is a reference to a hash, which must contain at least
+two keys: <code>count</code>, which is the count of times that address has been
+encountered before; and <code>totscore</code>, which is the total of all scores for
+messages associated with that address. From these two fields, an average
+score will be calculated, and the score for the current message will be
+regressed towards that mean message score.</p>
+</dd>
+<dd>
+<p>The hash can contain whatever other data your back-end needs to store,
+under other keys.</p>
+</dd>
+<dd>
+<p>The method should never return <code>undef</code>, or a hash that does not contain
+a <code>count</code> key and a <code>totscore</code> key.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_score">$entry = $addrlist->add_score($entry, $score);</a></strong><br />
+</dt>
+<dd>
+This method should add the given score to the whitelist database for the
+given entry, and then return the new entry.
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_entry">$entry = $addrlist->remove_entry ($entry);</a></strong><br />
+</dt>
+<dd>
+This method should remove the given entry from the whitelist database.
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$entry = $addrlist->finish ();</a></strong><br />
+</dt>
+<dd>
+Clean up, if necessary. Called by SpamAssassin when it has finished
+checking, or adding to, the auto-whitelist database.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.txt?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.txt Wed Jul 25 05:52:42 2007
@@ -0,0 +1,59 @@
+NAME
+ Mail::SpamAssassin::PersistentAddrList - persistent address list base
+ class
+
+SYNOPSIS
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...
+
+ SpamAssassin will call:
+
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...
+
+DESCRIPTION
+ All persistent address list implementations, used by the auto-whitelist
+ code to track known-good email addresses, use this as a base class.
+
+ See "Mail::SpamAssassin::DBBasedAddrList" for an example.
+
+METHODS
+ $factory = PersistentAddrListSubclass->new();
+ This creates a factory object, which SpamAssassin will call to
+ create a new checker object for the persistent address list.
+
+ my $addrlist = $factory->new_checker();
+ Create a new address-list checker object from the factory. Called by
+ the SpamAssassin classes.
+
+ $entry = $addrlist->get_addr_entry ($addr);
+ Given an email address $addr, return an entry object with the
+ details of that address.
+
+ The entry object is a reference to a hash, which must contain at
+ least two keys: "count", which is the count of times that address
+ has been encountered before; and "totscore", which is the total of
+ all scores for messages associated with that address. From these two
+ fields, an average score will be calculated, and the score for the
+ current message will be regressed towards that mean message score.
+
+ The hash can contain whatever other data your back-end needs to
+ store, under other keys.
+
+ The method should never return "undef", or a hash that does not
+ contain a "count" key and a "totscore" key.
+
+ $entry = $addrlist->add_score($entry, $score);
+ This method should add the given score to the whitelist database for
+ the given entry, and then return the new entry.
+
+ $entry = $addrlist->remove_entry ($entry);
+ This method should remove the given entry from the whitelist
+ database.
+
+ $entry = $addrlist->finish ();
+ Clean up, if necessary. Called by SpamAssassin when it has finished
+ checking, or adding to, the auto-whitelist database.
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,1096 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Plugin - SpamAssassin plugin base class</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <ul>
+
+ <li><a href="#spamassassin_configuration_">SpamAssassin configuration:</a></li>
+ <li><a href="#perl_code_">Perl code:</a></li>
+ </ul>
+
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#interface">INTERFACE</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#helper_apis">HELPER APIS</a></li>
+ <li><a href="#registering_eval_rules">REGISTERING EVAL RULES</a></li>
+ <li><a href="#standard_arguments_for_rule_types">STANDARD ARGUMENTS FOR RULE TYPES</a></li>
+ <li><a href="#backwards_compatibility">BACKWARDS COMPATIBILITY</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin - SpamAssassin plugin base class</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<h2><a name="spamassassin_configuration_">SpamAssassin configuration:</a></h2>
+<pre>
+ loadplugin MyPlugin /path/to/myplugin.pm</pre>
+<p>
+</p>
+<h2><a name="perl_code_">Perl code:</a></h2>
+<pre>
+ package MyPlugin;</pre>
+<pre>
+ use Mail::SpamAssassin::Plugin;
+ our @ISA = qw(Mail::SpamAssassin::Plugin);</pre>
+<pre>
+ sub new {
+ my ($class, $mailsa) = @_;
+
+ # the usual perlobj boilerplate to create a subclass object
+ $class = ref($class) || $class;
+ my $self = $class->SUPER::new($mailsa);
+ bless ($self, $class);
+
+ # then register an eval rule, if desired...
+ $self->register_eval_rule ("check_for_foo");</pre>
+<pre>
+ # and return the new plugin object
+ return $self;
+ }</pre>
+<pre>
+ ...methods...</pre>
+<pre>
+ 1;</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This is the base class for SpamAssassin plugins; all plugins must be objects
+that implement this class.</p>
+<p>This class provides no-op stub methods for all the callbacks that a plugin
+can receive. It is expected that your plugin will override one or more
+of these stubs to perform its actions.</p>
+<p>SpamAssassin implements a plugin chain; each callback event is passed to each
+of the registered plugin objects in turn. Any plugin can call
+<a href="#item_inhibit_further_callbacks"><code>$self->inhibit_further_callbacks()</code></a> to block delivery of that event to
+later plugins in the chain. This is useful if the plugin has handled the
+event, and there will be no need for later plugins to handle it as well.</p>
+<p>If you're looking to write a simple eval rule, skip straight to
+<a href="#item_register_eval_rule"><code>register_eval_rule()</code></a>, below.</p>
+<p>
+</p>
+<hr />
+<h1><a name="interface">INTERFACE</a></h1>
+<p>In all the plugin APIs below, <code>options</code> refers to a reference to a hash
+containing name-value pairs. This is used to ensure future-compatibility, in
+that we can add new options in future without affecting objects built to an
+earlier version of the API.</p>
+<p>For example, here would be how to print out the <a href="#item_line"><code>line</code></a> item in a
+<a href="#item_parse_config"><code>parse_config()</code></a> method:</p>
+<pre>
+ sub parse_config {
+ my ($self, $opts) = @_;
+ print "MyPlugin: parse_config got ".$opts->{line}."\n";
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>The following methods can be overridden by subclasses to handle events
+that SpamAssassin will call back to:</p>
+<dl>
+<dt><strong><a name="item_new">$plugin = MyPluginClass->new ($mailsaobject)</a></strong><br />
+</dt>
+<dd>
+Constructor. Plugins that need to register themselves will need to
+define their own; the default super-class constructor will work fine
+for plugins that just override a method.
+</dd>
+<dd>
+<p>Note that subclasses must provide the <code>$mailsaobject</code> to the
+superclass constructor, like so:</p>
+</dd>
+<dd>
+<pre>
+ my $self = $class->SUPER::new($mailsaobject);</pre>
+</dd>
+<dd>
+<p>Lifecycle note: plugins that will need to store per-scan state should not store
+that on the Plugin object; see <a href="#item_check_start"><code>check_start()</code></a> below. It is also likewise
+recommended that configuration settings be stored on the Conf object; see
+<a href="#item_parse_config"><code>parse_config()</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_parse_config">$plugin->parse_config ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Parse a configuration line that hasn't already been handled. <code>options</code>
+is a reference to a hash containing these options:
+</dd>
+<dl>
+<dt><strong><a name="item_line">line</a></strong><br />
+</dt>
+<dd>
+The line of configuration text to parse. This has leading and trailing
+whitespace, and comments, removed.
+</dd>
+<p></p>
+<dt><strong><a name="item_key">key</a></strong><br />
+</dt>
+<dd>
+The configuration key; ie. the first ``word'' on the line.
+</dd>
+<p></p>
+<dt><strong><a name="item_value">value</a></strong><br />
+</dt>
+<dd>
+The configuration value; everything after the first ``word'' and
+any whitespace after that.
+</dd>
+<p></p>
+<dt><strong><a name="item_conf">conf</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p>
+<dt><strong><a name="item_user_config">user_config</a></strong><br />
+</dt>
+<dd>
+A boolean: <code>1</code> if reading a user's configuration, <code>0</code> if reading the
+system-wide configuration files.
+</dd>
+<p></p></dl>
+<p>If the configuration line was a setting that is handled by this plugin, the
+method implementation should call <a href="#item_inhibit_further_callbacks"><code>$self->inhibit_further_callbacks()</code></a>.</p>
+<p>If the setting is not handled by this plugin, the method should return <code>0</code> so
+that a later plugin may handle it, or so that SpamAssassin can output a warning
+message to the user if no plugin understands it.</p>
+<p>Lifecycle note: it is suggested that configuration be stored on the
+<code>Mail::SpamAssassin::Conf</code> object in use, instead of the plugin object itself.
+That can be found as <code>$plugin->{main}->{conf}</code>. This allows per-user and
+system-wide configuration to be dealt with correctly, with per-user overriding
+system-wide.</p>
+<dt><strong><a name="item_finish_parsing_end">$plugin->finish_parsing_end ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that the system-wide configuration parsing has just finished, and
+SpamAssassin is nearly ready to check messages.
+</dd>
+<dd>
+<p><code>options</code> is a reference to a hash containing these options:</p>
+</dd>
+<dl>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p></dl>
+<p>Note: there are no guarantees that the internal data structures of
+SpamAssassin will not change from release to release. In particular to
+this plugin hook, if you modify the rules data structures in a
+third-party plugin, all bets are off until such time that an API is
+present for modifying that configuration data.</p>
+<dt><strong><a name="item_user_conf_parsing_end">$plugin->user_conf_parsing_end ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that the per-user configuration parsing has just finished, and
+SpamAssassin is nearly ready to check messages. If <code>allow_user_rules</code>
+is enabled in the configuration, it is possible that additional rules
+have been added in the user configuration file, since the
+<a href="#item_finish_parsing_end"><code>finish_parsing_end</code></a> plugin hook invocation was called.
+</dd>
+<dd>
+<p><code>options</code> is a reference to a hash containing these options:</p>
+</dd>
+<dl>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_signal_user_changed">$plugin->signal_user_changed ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that the current user has changed for a new one.
+</dd>
+<dl>
+<dt><strong><a name="item_username">username</a></strong><br />
+</dt>
+<dd>
+The new user's username.
+</dd>
+<p></p>
+<dt><strong><a name="item_user_dir">user_dir</a></strong><br />
+</dt>
+<dd>
+The new user's home directory. (equivalent to <code>~</code>.)
+</dd>
+<p></p>
+<dt><strong><a name="item_userstate_dir">userstate_dir</a></strong><br />
+</dt>
+<dd>
+The new user's storage directory. (equivalent to <code>~/.spamassassin</code>.)
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_services_authorized_for_username">$plugin->services_authorized_for_username ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Validates that a given username is authorized to use certain services.
+</dd>
+<dd>
+<p>In order to authorize a user, the plugin should first check that it can
+handle any of the services passed into the method and then set the value
+for each allowed service to true (or any non-negative value).</p>
+</dd>
+<dd>
+<p>The current supported services are: bayessql</p>
+</dd>
+<dl>
+<dt><strong>username</strong><br />
+</dt>
+<dd>
+A username
+</dd>
+<p></p>
+<dt><strong><a name="item_services">services</a></strong><br />
+</dt>
+<dd>
+Reference to a hash containing the services you want to check.
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'bayessql' => 0</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<p></p>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_compile_now_start">$plugin->compile_now_start ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+This is called at the beginning of Mail::SpamAssassin::compile_now() so
+plugins can do any necessary initialization for multi-process
+SpamAssassin (such as spamd or mass-check -j).
+</dd>
+<dl>
+<dt><strong><a name="item_use_user_prefs">use_user_prefs</a></strong><br />
+</dt>
+<dd>
+The value of $use_user_prefs option in compile_now().
+</dd>
+<p></p>
+<dt><strong><a name="item_keep_userstate">keep_userstate</a></strong><br />
+</dt>
+<dd>
+The value of $keep_userstate option in compile_now().
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_compile_now_finish">$plugin->compile_now_finish ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+This is called at the end of Mail::SpamAssassin::compile_now() so
+plugins can do any necessary initialization for multi-process
+SpamAssassin (such as spamd or mass-check -j).
+</dd>
+<dl>
+<dt><strong>use_user_prefs</strong><br />
+</dt>
+<dd>
+The value of $use_user_prefs option in compile_now().
+</dd>
+<p></p>
+<dt><strong>keep_userstate</strong><br />
+</dt>
+<dd>
+The value of $keep_userstate option in compile_now().
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_start">$plugin->check_start ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message check operation is starting.
+</dd>
+<dl>
+<dt><strong><a name="item_permsgstatus">permsgstatus</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<dd>
+<p>Lifecycle note: it is recommended that rules that need to track test state on a
+per-scan basis should store that state on this object, not on the plugin object
+itself, since the plugin object will be shared between all active scanners.</p>
+</dd>
+<dd>
+<p>The message being scanned is accessible through the
+<code>$permsgstatus->get_message()</code> API; there are a number of other public
+APIs on that object, too. See <code>Mail::SpamAssassin::PerMsgStatus</code> perldoc.</p>
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_main">$plugin->check_main ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message should be checked. Note that implementations of
+this hook should return <code>1</code>.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_tick">$plugin->check_tick ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called periodically during a message check operation. A callback set for
+this method is a good place to run through an event loop dealing with
+network events triggered in a <code>parse_metadata</code> method, for example.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_post_dnsbl">$plugin->check_post_dnsbl ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called after the DNSBL results have been harvested. This is a good
+place to harvest your own asynchronously-started network lookups.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_post_learn">$plugin->check_post_learn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called after auto-learning may (or may not) have taken place. If you
+wish to perform additional learning, whether or not auto-learning
+happens, this is the place to do it.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_end">$plugin->check_end ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message check operation has just finished, and the
+results are about to be returned to the caller.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+The current score, names of rules that hit, etc. can be retrieved
+using the public APIs on this object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_finish_tests">$plugin->finish_tests ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called via SpamAssassin::finish and should clear up any tests that a plugin
+has added to the namespace.
+</dd>
+<dd>
+<p>In certain circumstances, plugins may find it useful to compile
+perl functions from the ruleset, on the fly. It is important to
+remove these once the <code>Mail::SpamAssassin</code> object is deleted,
+however, and this API allows this.</p>
+</dd>
+<dd>
+<p>Each plugin is responsible for its own generated perl functions.</p>
+</dd>
+<dl>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p>
+<dt><strong><a name="item_extract_metadata">$plugin->extract_metadata ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message is being mined for metadata. Some plugins may wish
+to add their own metadata as well.
+</dd>
+<dl>
+<dt><strong><a name="item_msg">msg</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Message</code> object for this message.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_parsed_metadata">$plugin->parsed_metadata ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message's metadata has been parsed, and can now be
+accessed by the plugin.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_start_rules">$plugin->start_rules ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called before testing a set of rules of a given type and priority.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p>
+<dt><strong><a name="item_ruletype">ruletype</a></strong><br />
+</dt>
+<dd>
+The type of the rules about to be performed.
+</dd>
+<p></p>
+<dt><strong><a name="item_priority">priority</a></strong><br />
+</dt>
+<dd>
+The priority level of the rules about to be performed.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_hit_rule">$plugin->hit_rule ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a rule fires.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p>
+<dt><strong>ruletype</strong><br />
+</dt>
+<dd>
+The type of the rule that fired.
+</dd>
+<p></p>
+<dt><strong><a name="item_rulename">rulename</a></strong><br />
+</dt>
+<dd>
+The name of the rule that fired.
+</dd>
+<p></p>
+<dt><strong><a name="item_score">score</a></strong><br />
+</dt>
+<dd>
+The rule's score in the active scoreset.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_ran_rule">$plugin->ran_rule ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called after a rule has been tested, whether or not it fired. When the
+rule fires, the hit_rule callback is always called before this.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p>
+<dt><strong>ruletype</strong><br />
+</dt>
+<dd>
+The type of the rule that was tested.
+</dd>
+<p></p>
+<dt><strong>rulename</strong><br />
+</dt>
+<dd>
+The name of the rule that was tested.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_autolearn_discriminator">$plugin->autolearn_discriminator ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Control whether a just-scanned message should be learned as either
+spam or ham. This method should return one of <code>1</code> to learn
+the message as spam, <code>0</code> to learn as ham, or <code>undef</code> to not
+learn from the message at all.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_autolearn">$plugin->autolearn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message is about to be auto-learned as either ham or spam.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p>
+<dt><strong><a name="item_isspam">isspam</a></strong><br />
+</dt>
+<dd>
+<code>1</code> if the message is spam, <code>0</code> if ham.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_per_msg_finish">$plugin->per_msg_finish ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a <code>Mail::SpamAssassin::PerMsgStatus</code> object is being
+destroyed, and any per-scan context held on that object by this
+plugin should be destroyed as well.
+</dd>
+<dd>
+<p>Normally, any member variables on the <code>PerMsgStatus</code> object will be cleaned up
+automatically -- but if your plugin has made a circular reference on that
+object, this is the place to break them so that garbage collection can operate
+correctly.</p>
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_have_shortcircuited">$plugin->have_shortcircuited ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Has the current scan operation 'short-circuited'? In other words, can
+further scanning be skipped, since the message is already definitively
+classified as either spam or ham?
+</dd>
+<dd>
+<p>Plugins should return <code>0</code> to indicate that scanning should continue,
+or <code>1</code> to indicate that short-circuiting has taken effect.</p>
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_learn">$plugin->bayes_learn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes learn operation.
+</dd>
+<dd>
+<p>This phase is the best place to map the raw (original) token value
+to the SHA1 hashed value.</p>
+</dd>
+<dl>
+<dt><strong><a name="item_toksref">toksref</a></strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. The hash takes the
+format of:
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'SHA1 Hash Value' => 'raw (original) value'</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<dd>
+<p>NOTE: This data structure has changed since it was originally introduced
+in version 3.0.0. The values are no longer perl anonymous hashes, they
+are a single string containing the raw token value. You can test for
+backwards compatability by checking to see if the value for a key is a
+reference to a perl HASH, for instance:</p>
+</dd>
+<dd>
+<p>if (ref($toksref->{$sometokenkey}) eq 'HASH') {...</p>
+</dd>
+<dd>
+<p>If it is, then you are using the old interface, otherwise you are using
+the current interface.</p>
+</dd>
+<p></p>
+<dt><strong>isspam</strong><br />
+</dt>
+<dd>
+Boolean value stating what flavor of message the tokens represent, if
+true then message was specified as spam, false is nonspam. Note, when
+function is scan then isspam value is not valid.
+</dd>
+<p></p>
+<dt><strong><a name="item_msgid">msgid</a></strong><br />
+</dt>
+<dd>
+Generated message id of the message just learned.
+</dd>
+<p></p>
+<dt><strong><a name="item_msgatime">msgatime</a></strong><br />
+</dt>
+<dd>
+Received date of the current message or current time if received date
+could not be determined. In addition, if the receive date is more than
+24 hrs into the future it will be reset to current datetime.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_forget">$plugin->bayes_forget ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes forget operation.
+</dd>
+<dl>
+<dt><strong>toksref</strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. See bayes_learn
+documentation for additional information on the format.
+</dd>
+<p></p>
+<dt><strong>isspam</strong><br />
+</dt>
+<dd>
+Boolean value stating what flavor of message the tokens represent, if
+true then message was specified as spam, false is nonspam. Note, when
+function is scan then isspam value is not valid.
+</dd>
+<p></p>
+<dt><strong>msgid</strong><br />
+</dt>
+<dd>
+Generated message id of the message just forgotten.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_scan">$plugin->bayes_scan ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes scan operation. NOTE: Will not be
+called in case of error or if the message is otherwise skipped.
+</dd>
+<dl>
+<dt><strong>toksref</strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. See bayes_learn
+documentation for additional information on the format.
+</dd>
+<p></p>
+<dt><strong><a name="item_probsref">probsref</a></strong><br />
+</dt>
+<dd>
+Reference to hash of calculated probabilities for tokens found in
+the database.
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'SHA1 Hash Value' => {</pre>
+</dd>
+<dd>
+<pre>
+ 'prob' => 'calculated probability',</pre>
+</dd>
+<dd>
+<pre>
+ 'spam_count' => 'Total number of spam msgs w/ token',</pre>
+</dd>
+<dd>
+<pre>
+ 'ham_count' => 'Total number of ham msgs w/ token',</pre>
+</dd>
+<dd>
+<pre>
+ 'atime' => 'Atime value for token in database'</pre>
+</dd>
+<dd>
+<pre>
+ }</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<p></p>
+<dt><strong>score</strong><br />
+</dt>
+<dd>
+Score calculated for this particular message.
+</dd>
+<p></p>
+<dt><strong>msgatime</strong><br />
+</dt>
+<dd>
+Calculated atime of the message just learned, note it may have been adjusted
+if it was determined to be too far into the future.
+</dd>
+<p></p>
+<dt><strong><a name="item_significant_tokens">significant_tokens</a></strong><br />
+</dt>
+<dd>
+Array ref of the tokens found to be significant in determining the score for
+this message.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_plugin_report">$plugin->plugin_report ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called if the message is to be reported as spam. If the reporting system is
+available, the variable <code>$options-<gt</code>{report}-><gt>report_available}> should
+be set to <code>1</code>; if the reporting system successfully reported the message, the
+variable <code>$options-<gt</code>{report}-><gt>report_return}> should be set to <code>1</code>.
+</dd>
+<dl>
+<dt><strong><a name="item_report">report</a></strong><br />
+</dt>
+<dd>
+Reference to the Reporter object (<code>$options-<gt</code>{report}> in the
+paragraph above.)
+</dd>
+<p></p>
+<dt><strong><a name="item_text">text</a></strong><br />
+</dt>
+<dd>
+Reference to a markup removed copy of the message in scalar string format.
+</dd>
+<p></p>
+<dt><strong>msg</strong><br />
+</dt>
+<dd>
+Reference to the original message object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_plugin_revoke">$plugin->plugin_revoke ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called if the message is to be reported as ham (revokes a spam report). If the
+reporting system is available, the variable
+<code>$options-<gt</code>{revoke}-><gt>revoke_available}> should be set to <code>1</code>; if the
+reporting system successfully revoked the message, the variable
+<code>$options-<gt</code>{revoke}-><gt>revoke_return}> should be set to <code>1</code>.
+</dd>
+<dl>
+<dt><strong><a name="item_revoke">revoke</a></strong><br />
+</dt>
+<dd>
+Reference to the Reporter object (<code>$options-<gt</code>{revoke}> in the
+paragraph above.)
+</dd>
+<p></p>
+<dt><strong>text</strong><br />
+</dt>
+<dd>
+Reference to a markup removed copy of the message in scalar string format.
+</dd>
+<p></p>
+<dt><strong>msg</strong><br />
+</dt>
+<dd>
+Reference to the original message object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_whitelist_address">$plugin->whitelist_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to add an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong><a name="item_address">address</a></strong><br />
+</dt>
+<dd>
+Address you wish to add.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_blacklist_address">$plugin->blacklist_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to add an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong>address</strong><br />
+</dt>
+<dd>
+Address you wish to add.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_remove_address">$plugin->remove_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to remove an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong>address</strong><br />
+</dt>
+<dd>
+Address you wish to remove.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_spamd_child_init">$plugin->spamd_child_init ()</a></strong><br />
+</dt>
+<dd>
+Called when a new child starts up under spamd.
+</dd>
+<p></p>
+<dt><strong><a name="item_log_scan_result">$plugin->log_scan_result ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when spamd has completed scanning a message. Currently,
+only spamd calls this API.
+</dd>
+<dl>
+<dt><strong><a name="item_result">result</a></strong><br />
+</dt>
+<dd>
+The <code>'result: ...'</code> line for this scan. Format is as described
+at <strong><a href="http://wiki.apache.org/spamassassin/SpamdSyslogFormat">http://wiki.apache.org/spamassassin/SpamdSyslogFormat</a></strong>.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_spamd_child_post_connection_close">$plugin->spamd_child_post_connection_close ()</a></strong><br />
+</dt>
+<dd>
+Called when child returns from handling a connection.
+</dd>
+<dd>
+<p>If there was an accept failure, the child will die and this code will
+not be called.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$plugin->finish ()</a></strong><br />
+</dt>
+<dd>
+Called when the <code>Mail::SpamAssassin</code> object is destroyed.
+</dd>
+<p></p></dl>
+</dl>
+<p>
+</p>
+<hr />
+<h1><a name="helper_apis">HELPER APIS</a></h1>
+<p>These methods provide an API for plugins to register themselves
+to receive specific events, or control the callback chain behaviour.</p>
+<dl>
+<dt><strong><a name="item_register_eval_rule">$plugin->register_eval_rule ($nameofevalsub)</a></strong><br />
+</dt>
+<dd>
+Plugins that implement an eval test will need to call this, so that
+SpamAssassin calls into the object when that eval test is encountered.
+See the <strong>REGISTERING EVAL RULES</strong> section for full details.
+</dd>
+<p></p>
+<dt><strong><a name="item_register_generated_rule_method">$plugin->register_generated_rule_method ($nameofsub)</a></strong><br />
+</dt>
+<dd>
+In certain circumstances, plugins may find it useful to compile
+perl functions from the ruleset, on the fly. It is important to
+remove these once the <code>Mail::SpamAssassin</code> object is deleted,
+however, and this API allows this.
+</dd>
+<dd>
+<p>Once the method <code>$nameofsub</code> has been generated, call this API
+with the name of the method (including full package scope).
+This indicates that it's a temporary piece of generated code,
+built from the SpamAssassin ruleset, and when
+<a href="#item_finish"><code>Mail::SpamAssassin::finish()</code></a> is called, the method will
+be destroyed.</p>
+</dd>
+<dd>
+<p>This API was added in SpamAssassin 3.2.0.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_register_method_priority">$plugin->register_method_priority($methodname, $priority)</a></strong><br />
+</dt>
+<dd>
+Indicate that the method named <code>$methodname</code> on the current object
+has a callback priority of <code>$priority</code>.
+</dd>
+<dd>
+<p>This is used by the plugin handler to determine the relative order of
+callbacks; plugins with lower-numbered priorities are called before plugins
+with higher-numbered priorities. Each method can have a different priority
+value. The default value is <code>0</code>. The ordering of callbacks to methods with
+equal priority is undefined.</p>
+</dd>
+<dd>
+<p>Typically, you only need to worry about this if you need to ensure your
+plugin's method is called before another plugin's implementation of that
+method. It should be called from your plugin's constructor.</p>
+</dd>
+<dd>
+<p>This API was added in SpamAssassin 3.2.0.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_inhibit_further_callbacks">$plugin-><code>inhibit_further_callbacks()</code></a></strong><br />
+</dt>
+<dd>
+Tells the plugin handler to inhibit calling into other plugins in the plugin
+chain for the current callback. Frequently used when parsing configuration
+settings using <a href="#item_parse_config"><code>parse_config()</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_dbg"><code>dbg($message)</code></a></strong><br />
+</dt>
+<dd>
+Output a debugging message <code>$message</code>, if the SpamAssassin object is running
+with debugging turned on.
+</dd>
+<dd>
+<p><em>NOTE:</em> This function is not available in the package namespace
+of general plugins and can't be called via $self->dbg(). If a
+plugin wishes to output debug information, it should call
+<a href="#item_dbg"><code>Mail::SpamAssassin::Plugin::dbg($msg)</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_info"><code>info($message)</code></a></strong><br />
+</dt>
+<dd>
+Output an informational message <code>$message</code>, if the SpamAssassin object
+is running with informational messages turned on.
+</dd>
+<dd>
+<p><em>NOTE:</em> This function is not available in the package namespace
+of general plugins and can't be called via $self->info(). If a
+plugin wishes to output debug information, it should call
+<a href="#item_info"><code>Mail::SpamAssassin::Plugin::info($msg)</code></a>.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="registering_eval_rules">REGISTERING EVAL RULES</a></h1>
+<p>Plugins that implement an eval test must register the methods that can be
+called from rules in the configuration files, in the plugin class' constructor.</p>
+<p>For example,</p>
+<pre>
+ $plugin->register_eval_rule ('check_for_foo')</pre>
+<p>will cause <code>$plugin->check_for_foo()</code> to be called for this
+SpamAssassin rule:</p>
+<pre>
+ header FOO_RULE eval:check_for_foo()</pre>
+<p>Note that eval rules are passed the following arguments:</p>
+<dl>
+<dt><strong><a name="item__2d_the_plugin_object_itself">- The plugin object itself</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_the_mail_3a_3aspamassassin_3a_3apermsgstatus_o">- The <code>Mail::SpamAssassin::PerMsgStatus</code> object calling the rule</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_standard_arguments_for_the_rule_type_in_use">- standard arguments for the rule type in use</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_any_and_all_arguments_as_specified_in_the_conf">- any and all arguments as specified in the configuration file</a></strong><br />
+</dt>
+</dl>
+<p>In other words, the eval test method should look something like this:</p>
+<pre>
+ sub check_for_foo {
+ my ($self, $permsgstatus, ...arguments...) = @_;
+ ...code returning 0 or 1
+ }</pre>
+<p>Note that the headers can be accessed using the <code>get()</code> method on the
+<code>Mail::SpamAssassin::PerMsgStatus</code> object, and the body by
+<code>get_decoded_stripped_body_text_array()</code> and other similar methods.
+Similarly, the <code>Mail::SpamAssassin::Conf</code> object holding the current
+configuration may be accessed through <code>$permsgstatus->{main}->{conf}</code>.</p>
+<p>The eval rule should return <code>1</code> for a hit, or <code>0</code> if the rule
+is not hit.</p>
+<p>State for a single message being scanned should be stored on the <code>$checker</code>
+object, not on the <code>$self</code> object, since <code>$self</code> persists between scan
+operations. See the 'lifecycle note' on the <a href="#item_check_start"><code>check_start()</code></a> method above.</p>
+<p>
+</p>
+<hr />
+<h1><a name="standard_arguments_for_rule_types">STANDARD ARGUMENTS FOR RULE TYPES</a></h1>
+<p>Plugins will be called with the same arguments as a standard EvalTest.
+Different rule types receive different information by default:</p>
+<dl>
+<dt><strong><a name="item__2d_header_tests_3a_no_extra_arguments">- header tests: no extra arguments</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_body_tests_3a_fully_rendered_message_as_array_">- body tests: fully rendered message as array reference</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_rawbody_tests_3a_fully_decoded_message_as_arra">- rawbody tests: fully decoded message as array reference</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_full_tests_3a_pristine_message_as_scalar_refer">- full tests: pristine message as scalar reference</a></strong><br />
+</dt>
+</dl>
+<p>The configuration file arguments will be passed in after the standard
+arguments.</p>
+<p>
+</p>
+<hr />
+<h1><a name="backwards_compatibility">BACKWARDS COMPATIBILITY</a></h1>
+<p>Note that if you write a plugin and need to determine if a particular
+helper method is supported on <code>Mail::SpamAssassin::Plugin</code>, you
+can do this:</p>
+<pre>
+ if ($self->can("name_of_method")) {
+ eval {
+ $self->name_of_method(); # etc.
+ }
+ } else {
+ # take fallback action
+ }</pre>
+<p>The same applies for the public APIs on objects of other types, such as
+<code>Mail::SpamAssassin::PerMsgStatus</code>.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::SpamAssassin</code></p>
+<p><code>Mail::SpamAssassin::PerMsgStatus</code></p>
+<p><a href="http://wiki.apache.org/spamassassin/PluginWritingTips">http://wiki.apache.org/spamassassin/PluginWritingTips</a></p>
+<p><a href="http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163">http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163</a></p>
+
+</body>
+
+</html>