svn commit: r756190 - in /spamassassin/trunk/lib/Mail: SpamAssassin.pm SpamAssassin/Message.pm

[mm...@apache.org]

Author: mmartinec
Date: Thu Mar 19 20:52:35 2009
New Revision: 756190

URL: http://svn.apache.org/viewvc?rev=756190&view=rev
Log:
Bug 6088: Adding one optional arg to M::S::parse allows
caller to pass additional info to SA

Modified:
    spamassassin/trunk/lib/Mail/SpamAssassin.pm
    spamassassin/trunk/lib/Mail/SpamAssassin/Message.pm

Modified: spamassassin/trunk/lib/Mail/SpamAssassin.pm
URL: http://svn.apache.org/viewvc/spamassassin/trunk/lib/Mail/SpamAssassin.pm?rev=756190&r1=756189&r2=756190&view=diff
==============================================================================
--- spamassassin/trunk/lib/Mail/SpamAssassin.pm (original)
+++ spamassassin/trunk/lib/Mail/SpamAssassin.pm Thu Mar 19 20:52:35 2009
@@ -449,7 +449,7 @@
 
 ###########################################################################
 
-=item parse($message, $parse_now)
+=item parse($message, $parse_now [, $suppl_attrib])
 
 Parse will return a Mail::SpamAssassin::Message object with just the
 headers parsed.  When calling this function, there are two optional
@@ -466,18 +466,37 @@
 needs the pristine header and body which is always parsed and stored
 by this function.
 
+The optional last argument I<$suppl_attrib> provides a way for a caller
+to pass additional information about a message to SpamAssassin. It is
+either undef, or a ref to a hash where each key/value pair provides some
+supplementary attribute of the message, typically information that cannot
+be deduced from the message itself, or is hard to do so reliably, or would
+represent unnecessary work for SpamAssassin to obtain it. The argument will
+be stored to a Mail::SpamAssassin::Message object as 'suppl_attrib', thus
+made available to the rest of the code as well as to plugins. The exact list
+of attributes will evolve through time, any unknown attributes should be
+ignored. Possible examples are: SMTP envelope information, a flag indicating
+that a message as supplied by a caller was truncated due to size limit, an
+already verified list of DKIM signature objects, or perhaps a list of rule
+hits predetermined by a caller, which makes another possible way for a
+caller to provide meta information (instead of having to insert made-up
+header fields in order to pass information), or maybe just plain rule hits.
+
 For more information, please see the C<Mail::SpamAssassin::Message>
 and C<Mail::SpamAssassin::Message::Node> POD.
 
 =cut
 
 sub parse {
-  my($self, $message, $parsenow) = @_;
+  my($self, $message, $parsenow, $suppl_attrib) = @_;
   $self->init(1);
 
   my $timer = $self->time_method("parse");
 
-  my $msg = Mail::SpamAssassin::Message->new({message=>$message, parsenow=>$parsenow, normalize=>$self->{conf}->{normalize_charset}});
+  my $msg = Mail::SpamAssassin::Message->new({
+    message=>$message, parsenow=>$parsenow,
+    normalize=>$self->{conf}->{normalize_charset},
+    suppl_attrib=>$suppl_attrib });
 
   # bug 5069: The goal here is to get rendering plugins to do things
   # like OCR, convert doc and pdf to text, etc, though it could be anything

Modified: spamassassin/trunk/lib/Mail/SpamAssassin/Message.pm
URL: http://svn.apache.org/viewvc/spamassassin/trunk/lib/Mail/SpamAssassin/Message.pm?rev=756190&r1=756189&r2=756190&view=diff
==============================================================================
--- spamassassin/trunk/lib/Mail/SpamAssassin/Message.pm (original)
+++ spamassassin/trunk/lib/Mail/SpamAssassin/Message.pm Thu Mar 19 20:52:35 2009
@@ -114,6 +114,7 @@
   $self->{pristine_body} =	'';
   $self->{mime_boundary_state} = {};
   $self->{line_ending} =	"\012";
+  $self->{suppl_attrib} = $opts->{'suppl_attrib'};
 
   bless($self,$class);