NAME

Mail::SpamAssassin::Handler - superclass for MIME-part handlers

SYNOPSIS

package MyHandler;
use Mail::SpamAssassin::Handler;
our @ISA = qw(Mail::SpamAssassin::Handler);

sub new {
  my ($class, $mailsaobject) = @_;
  $class = ref($class) || $class;
  my $self = $class->SUPER::new($mailsaobject);
  bless ($self, $class);
  $self->register_handler('image/jpeg', 'handle_jpeg');
  return $self;
}

sub handle_jpeg {
  my ($self, $node, $permsgstatus) = @_;
  # ... analyse the part, optionally return synthetic child parts ...
  return [];
}

DESCRIPTION

A handler is a plugin that processes individual MIME parts: it registers itself for one or more content types with register_handler and is invoked once per matching part during message metadata extraction.

Mail::SpamAssassin::Handler is a thin subclass of Mail::SpamAssassin::Plugin. Handlers are loaded, configured and dispatched through the same machinery as plugins; inheriting from this class instead of from Mail::SpamAssassin::Plugin gives handlers a distinct identity (so they can be told apart with $obj->isa('Mail::SpamAssassin::Handler')) and a place for handler-specific behaviour to live in future. Handlers are loaded with the loadhandler / tryhandler configuration directives, and a block of configuration can be made conditional on a handler with ifhandler.

Everything in Mail::SpamAssassin::Plugin is available to handlers; only the handler-specific method below is added here.

$handler->register_handler ($mime_pattern, $nameofsub)

Register one of this handler's methods as the MIME-part handler for a content-type pattern. $mime_pattern is an exact type (image/jpeg) or a major-type glob (image/*); the most specific match wins. $nameofsub is the name of a method on this handler that will be called as $handler->$nameofsub($node, $permsgstatus) for each matching MIME part, during message metadata extraction (before body rules run and before the URI list is frozen).

The method may inject extracted text into the part with $node->set_rendered($text, $type), accumulate per-message findings on $permsgstatus, and return an arrayref of synthetic child-part specs ({ type => ..., data => $bytes, name => ... }) which are dispatched recursively -- or undef/[] for none.

SEE ALSO

Mail::SpamAssassin::Plugin